OpenAPI ドキュメント(OAS 3) から静的HTMLを作成する

モチベーション

OpenAPI (もしくは Swagger) で API ドキュメントを作成し、チームに共有したい。OpenAPI バージョン 3 以降を使いたい。

 

お手軽なのは SwaggerHub を利用することですが、これはちょっと高い。Swagger UI のコンテナを立ち上げるのもありです。しかし、そこまでしなくとも、可読性のある静的HTMLが得られるだけでいい。

その index.html を共有できればよい。

 

コンセプト

OpenAPI ドキュメント  (OpenAPI の仕様に則った openapi.yaml などのファイル)を静的HTMLとして出力する方法は、以下の Stack Overflow の記事に詳細があります。

Generate static docs with swagger - Stack Overflow

 

swagger-codegen コマンドに OpenAPI ドキュメントを与えれば良いのですが、swagger-codegen の環境を整えるのは、けっこう面倒だったため、こちらに手順を整理しました。

 

環境

以下の環境を事前に準備してください。

  • OpenJDK 8 以上($ javac -version が使える)
  • maven ($ mvn -v が使える)

 

サンプルデータ

今回は OpenAPI バージョン 3 の yaml をビルドします。もし必要があれば、公式のサンプルデータを利用してください。

OpenAPI-Specification/petstore.yaml at master · OAI/OpenAPI-Specification · GitHub 

 

 

ビルド手順

swagger-codegen の jar ファイルを作成する

OpenAPI ドキュメントから静的 HTML を生成するために swagger-codegen を利用します。

GitHub - swagger-api/swagger-codegen

 

現在(2019-05-13)、swagger-codegenv2 系と v3 系が並行してリリースされていますOpenAPI バージョン 3 をサポートしているのは swagger-codegen v3 のみです。OpenAPI バージョン 3 のビルドには、必ず swagger-codegen v3 以降を利用してください。

 

以下のコマンドを実行して、swagger-codegen の jar ファイルを作成してください。

 

初回ビルドでは、ライブラリのダウンロードなどに10分前後の時間がかかってしまうと思いますが、2回目以降はキャッシュされるので、高速に実行できるようになります。

 

OpenAPI ドキュメント (petstore.yaml) から静的HTMLを作成する

以下のコマンドを実行してください。

 

これにより out/index.html が作成されたら成功です。

f:id:komiyak:20190514095740p:plain

出力された index.html の例です。

 

まとめ

これまでの手順を、下記にまとめました。

 

開発時は Swagger Editor で yaml を編集し、フロントエンドエンジニアに API 仕様を連絡するときには、上記のコマンドを実行して、生成された HTML を配布します。