web-dev-qa-db-ja.com

Swagger仕様JSONからHTMLドキュメントへの変換

PHPで書かれたいくつかのREST AP​​Iについては、 Swagger ドキュメントを作成するように求められました。既存のAPIに注釈を追加し、そのようなドキュメンテーション、私は this editor を使用して今のところいくつかを生成しました。

そのエディターを使用して作成されたJSONファイルとYAMLファイルを保存し、今度は最終的な対話型Swaggerドキュメントを作成する必要があります（このステートメントは単純で曖昧に聞こえるかもしれません）。

Swagger JSON仕様ファイルを実際のSwaggerドキュメントに変換する方法を教えてください。

私はWindowsプラットフォームを使用していますが、Ant/Mavenについては何も知りません。

yamlswaggerswagger-php
69
Salil

これを行うツールを探していたとき、私はswagger-codegenに満足していなかったので、自分で書きました。 bootprint-swagger をご覧ください

swagger-codegenと比較した主な目標は、簡単なセットアップを提供することです（ただし、nodejsが必要です）。また、スタイリングとテンプレートを自分のニーズに合わせて簡単に調整できる必要があります。これは bootprint -projectのコア機能です

37
Nils Knappmeier

redoc-cliを使用してみてください。

bootprint-openapi を使用して、ファイルの束を生成していました（bundle.js、bundle.js.map、index.html、main.cssおよびmain.css.map）そして、 html-inline を使用して単一の.htmlファイルに変換し、単純なindex.htmlファイルを生成できます。

そして、私は redoc-cli 使用が非常に簡単で、出力は本当に2素晴らしい、単一で美しいindex.htmlファイル。

インストール：

npm install -g redoc-cli

使用法：

redoc-cli bundle -o index.html swagger.json
24
VicJordan

チェックアウト pretty-Swag

持っている

  1. Swagger-Editor の右パネルに似ている
  2. 検索/フィルター
  3. スキーマの折りたたみ
  4. ライブフィードバック
  5. 単一のhtmlファイルとして出力

Swagger Editorを見ていて、プレビューペインをエクスポートできると思っていましたが、エクスポートできないことが判明しました。それで、私はそれの私自身のバージョンを書きました。

完全な開示：私はツールの作成者です。

18
TLJ

GitHubの swagger-api/swagger-codegen プロジェクトを参照してください。プロジェクトREADMEは、それを使用して静的HTMLを生成する方法を示しています。 静的HTML APIドキュメントの生成 を参照してください。

Swagger.jsonを表示するには、 Swagger UIをインストール を実行します。 Webサーバー（GitHubからリポジトリを複製した後のdistフォルダー）に展開し、ブラウザーでSwagger UIを表示します。これはJavaScriptアプリです。

13
djb

すべてが難しすぎるか、文書化が不十分だったので、単純なスクリプト swagger-yaml-to-html.py でこれを解決しました。

python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html

これはYAML向けですが、JSONで動作するように変更するのも簡単です。

10
oseiskar

私は多くの時間を費やし、多くの異なる解決策を試しました-最後にこのようにしました：

<html>
    <head>    
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/swagger-ui.css">
        <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
        <script>

            function render() {
                var ui = SwaggerUIBundle({
                    url:  `path/to/my/swagger.yaml`,
                    dom_id: '#swagger-ui',
                    presets: [
                        SwaggerUIBundle.presets.apis,
                        SwaggerUIBundle.SwaggerUIStandalonePreset
                    ]
                });
            }

        </script>
    </head>

    <body onload="render()">
        <div id="swagger-ui"></div>
    </body>
</html>

path/to/my/swagger.yamlが同じ場所から提供される必要があります。
（またはCORSヘッダーを使用）

8
Kris Randall

次の場所からswagger uiをダウンロードすることもできます。 https://github.com/swagger-api/swagger-ui

const ui = SwaggerUIBundle({
    url: ...,

に

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

distフォルダーには必要なものがすべて含まれており、そのまま配布できます。

6
user1928596

このリンクをご覧ください： http://zircote.com/swagger-php/installation.html

  1. Pharファイルをダウンロード https://github.com/zircote/swagger-php/blob/master/swagger.phar
  2. インストールComposer https://getcomposer.org/download/
  3. Composer.jsonを作成する
  4. Swagger-php/libraryのクローン
  5. Swagger-ui/libraryのクローン
  6. APIのリソースおよびモデルphpクラスを作成する
  7. PHPファイルを実行してjsonを生成します
  8. Api-doc.jsonでjsonのパスを指定します
  9. Swagger-ui distフォルダー内のindex.phpでapi-doc.jsonのパスを指定します

別のヘルプが必要な場合は、お気軽にお問い合わせください。

2
Syed Raza Mehdi

Yamlファイルからドキュメント（adocまたはmd）を生成する小さな Javaプログラム があります。

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withSwaggerMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withOutputLanguage(Language.DE)
        .build();

Swagger2MarkupConverter builder = Swagger2MarkupConverter.from(yamlFileAsString).withConfig(config).build();
return builder.toFileWithoutExtension(outFile);

残念ながら OpenAPI 2. のみをサポートしますが、 OpenAPI 3. はサポートしません。

1
Erando