Edited at

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


Intro

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

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

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


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

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

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


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 git@github.com: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を AmazonS3GithubPages といったサービスにホスティングさせることでAPI仕様書をインターネットに公開も簡単に出来そうですね。


関連