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-codegen は v2 系と v3 系が並行してリリースされています。OpenAPI バージョン 3 をサポートしているのは swagger-codegen v3 のみです。OpenAPI バージョン 3 のビルドには、必ず swagger-codegen v3 以降を利用してください。
以下のコマンドを実行して、swagger-codegen の jar ファイルを作成してください。
初回ビルドでは、ライブラリのダウンロードなどに10分前後の時間がかかってしまうと思いますが、2回目以降はキャッシュされるので、高速に実行できるようになります。
OpenAPI ドキュメント (petstore.yaml) から静的HTMLを作成する
以下のコマンドを実行してください。
これにより out/index.html が作成されたら成功です。
まとめ
これまでの手順を、下記にまとめました。
開発時は Swagger Editor で yaml を編集し、フロントエンドエンジニアに API 仕様を連絡するときには、上記のコマンドを実行して、生成された HTML を配布します。