[Swagger] OpenAPI3.0で記述したAPI仕様書をHTMLとして出力する

Intro

SwaggerUI を利用すると、OpenAPIで記述したAPI仕様書をHTTPサーバーとしてインターネットに公開したり、または ローカルにHTTPサーバーとして起動して確認できます。

チームで開発する場合、同じドキュメントを不特定多数のメンバーと共有して開発したくなるユースケースが発生することがあると思います。

SwaggerUI の Docker Image をサーバーとして起動させ配信したりする方法もありますが、何らかの社内の事情で使えない場合や、もう少し簡単に始めたい場合に、HTMLファイルとして出力し、ブラウザで確認するというアプローチもあります。

HTMLに変換してブラウザで確認する

OpenAPIで記述したファイルから、洗練されたスタイルが適用されたHTMLファイルにしてブラウザに確認するアプローチとしていくつかあります。

• swagger-codegen
• swagger-ui
• redoc

以下のファイルを参考にそれぞれドキュメントを生成してみます。

openapi.yaml

openapi: 3.0.0
info:
  version: 1.0.0
  title: Swagger sample
paths:
  /users:
    get:
      summary: Usersを取得するAPIです。
      responses:
        '200':
          description: HTTPステータスコード200と以下の情報を含むJSONオブジェクトを返します。
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                    example: 1234567

swagger-codegen

swagger-codegen をインストールし実行するとHTMLが生成されます。

$ brew install swagger-codegen

$ swagger-codegen generate -i openapi.yaml -l html -o /tmp/swagger-sample

swagger-ui

swagger-ui プロジェクト配下にある dist ディレクトリに必要なファイルが一式あります。

自身が作成した仕様書を表示したい場合は index.html に記述されているリンクを変更すればOKです。ディレクトリ一式をWebサーバーへアップロードすれば swagger-ui のスタイルのままドキュメントを閲覧することができます。

$ git clone [e-mail]:swagger-api/swagger-ui.git
$ cd swagger-ui/dist
$ vi index.html

index.html

     window.onload = function() {
       // Begin Swagger UI call region
       const ui = SwaggerUIBundle({
-        url: "https://petstore.swagger.io/v2/swagger.json",
+        url: "https://petstore.swagger.io/v2/swagger.yaml", ← ★ここを変更する★
         dom_id: '#swagger-ui',
         deepLinking: true,
         presets: [

ReDoc

Redocを使うとデフォルトでかっこいいドキュメントが出来上がります。
個人的には3カラムのRedocのドキュメントが好みです。redoc demo

README に書かれているように基本的にはリンクを書き換えるだけで動作します。また CLIも提供されているようです。今回はCliを使ってみます。

$ npm install -g redoc-cli
$ redoc-cli bundle openapi.yaml

まとめ

API仕様書を OpenAPI で記述していたら Swagger をはじめとした各種周辺ツールと簡単に連携できて良さそうです。

また、今回作成したHTMLを AmazonS3や GithubPages といったサービスにホスティングさせることでAPI仕様書をインターネットに公開も簡単に出来そうですね。

関連

• multi-file-swaggerでSwaggerファイルを分割してAPIドキュメントを管理する