API GatewayからSwagger +API Gateway 拡張の形式でエクスポートしたファイルからRedoc-CLIで静的ドキュメントを作成する方法

現在redoc-cliは非推奨になっています。後継は、@redocly/cliとなっています。

Swagger-UIを使用して静的ドキュメントを作成する方法を紹介しました。「API GatewayをエクスポートしてSwagger-UIを使う方法」

その他にも静的ドキュメント生成ツールはたくさんあるようで、Redocを紹介します。

コマンドラインから生成するのでredoc-cliをインストールします。

$ npm install -g redoc-cli

バージョン確認します。

$ redoc-cli --version

項目	バージョン
redoc-cli	0.9.4

API GatewayからOpenAPIのyamlをエクスポートします。「lambda-dev-oas30-apigateway.yaml」というファイル名とします。

redoc-cliではローカルサーバで起動して静的HTMLを見る方法と、静的HTMLを生成する方法の2通りあります。

カレントディレクトリにyamlを配置して以下を実行します。

$ redoc-cli serve aliastestlambda-api-dev-oas30-apigateway.yaml

「http://127.0.0.1:8080」を起動します。

奇麗にレンダリングされています。

今度は先ほどレンダリングされたHTMLを生成します。

$ redoc-cli bundle lambda-dev-oas30-apigateway.yaml

デフォルトでは「doc-static.html」が作成されますがオプションでファイル名は変更可能です。詳細はヘルプを見てください。

$ redoc-cli bundle --help

静的HTMLが生成されていることが確認できます。

生成されたHTMLを見ると、no summaryと表示されています。これはyamlにsummaryがないからです。

yamlのGETの部分にsummaryを追加します。

paths:
  /user:
    get:
      summary: GET TEST # summaryを追加
      responses:
        200:

これで再度HTMLを生成します。

summary(要約)が表示されました。その他にも色々詳細な記述が出来るので、「What Is OpenAPI?」を参照ください。

その他、HTML生成時にオプションで--options.hideDownloadButton=trueをつけるとダウンロードボタンが非表示になります。

$ redoc-cli bundle lambda-dev-oas30-apigateway.yaml --options.hideDownloadButton=true

--options.pathInMiddlePanel=trueをつけるとpathが表示されるようになります。

$ redoc-cli bundle lambda-dev-oas30-apigateway.yaml --options.hideDownloadButton=true --options.pathInMiddlePanel=true

KHI入社して退社。今はCONFRAGEで正社員です。関西で140-170/80～120万から受け付けております^^
得意技はJS(ES6),Java,AWSの大体のリソースです
コメントはやさしくお願いいたします^^
座右の銘は、「狭き門より入れ」「願わくは、我に七難八苦を与えたまえ」です^^

コメント