web-dev-qa-db-ja.com

swaggerを使用して静的ドキュメントを生成する

Swagger 2.0の静的ドキュメントを作成する方法はありますか？多分、editor.swagger.ioの「プレビュー」に似ています。

静的なHTMLファイルを取得して、それらを静的なドキュメントに含める必要があります。

これまでのところ、私はこれを行う方法を見つけていません。 swagger-codegens static-docsがありますが、これはswagger <= 1.2でのみ機能します。

swagger
52
romeovs

Swagger-codegenを使用します。

swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location>

HTMLテンプレートをカスタマイズする場合：

  1. github からswagger-codegenプロジェクトを複製します
  2. modules/swagger-codegen/src/main/resources/htmlDocs2フォルダーを別の場所にコピーします。例：cp -R modules/swagger-codegen/src/main/resources/htmlDocs2 ~/templates
  3. .mustacheの~/templatesテンプレートを変更して、要件に合わせます。
  4. 実行：swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location> -t <templates path> for <templates path>は、上記の例では~/templatesである必要があります。
25
BananaWanted

単純な方法で静的ドキュメントを生成したいだけなら、 Spectacle を検討してください。

npm install spectacle-docsは、package.jsonにスクリプトを配置する場合、またはどこでも使用できるようにする場合はnpm install -g spectacle-docsです。

その後、特定のディレクトリにビルドするオプション、サーバーを実行するオプション、および/または必要に応じてspecfileを監視して更新するオプションを使用して、spectacle spec.yamlを実行できます。

16
Will

2.0のstatic-docsは2.0向けに実装されています。ここで./bin/static-docs.shを参照してください。

https://github.com/swagger-api/swagger-codegen/tree/master/bin

5
fehguy

次を使用できます。

  • swagger-ui ：プロジェクトをgit cloneして、JSONをベースディレクトリにコピーするだけです
  • swagger-codegen
2
slal

Swagger 2.0を特に探している場合は、 Swagger仕様のJSONからHTMLドキュメントへの変換 での私の答えを指摘したいと思いますが、Swagger-Codegenは今ではSwagger 2.0をサポートしていると思います。

2
Nils Knappmeier

「静的な」ドキュメントにはいくつかの意味があります。

（エディターのプレビューなど）インタラクティブなディスプレイを探している場合、swagger-ui（ https://github.com/swagger-api/swagger-ui ）があります。

より静的なドキュメントを実行するcodegenのコード（たとえば、[Try it now]ボタンなし）は2.0にはまだ実装されていませんが、今後数週間で利用可能になるはずです。

1
Ron

プレビュードキュメントでClik、chromeアドオン 'Save Page WE'を使用（ページを右クリック-> 'save page we'）、結果は単一のhtmlファイルです（クリックできないので、すべてクリックする必要があります）見られたい）。

0
Jiro Matchonson

ここで説明する手順を使用しました http://ics.upjs.sk/~novotnyr/blog/2156/create-html-documentation-from-swagger-via-maven 。

Mavenを使用して静的ドキュメントを生成し、結果は非常に読みやすくなります。私はまだ試していませんが、高度な設定と拡張が可能です。

0
paul

私は通常 https://editor.swagger.io/ でそれを行います。インストールなどは必要ありません。

Ymlファイルをエディターにコピーし、「クライアントの生成> html2」を選択すると、静的なhtmlファイルがZipファイルに生成されます。

0
Semaphor

Spectacleの Docker image 静的ビルドを使用して、OpenAPI/Swagger仕様をspec.json（YAMLでも可能）で作成すると、次のように生成できます。

mkdir -m 777 build && docker run --rm \
    -v `pwd`/build:/tmp/build \
    -v `pwd`/spec.json:/tmp/spec.json \
    sourcey/spectacle \
    spectacle -t /tmp/build /tmp/spec.json
0
saaj