SwaggerでOpenAPI仕様書を作成、HTMLやMarkdownに変換する
yamlを直接編集とか無理
以前API BlueprintでAPI仕様書を書くという記事を書いた。
あれからまぁまぁ経ったがAPI Blueprintの先行きは暗い。
仕様もツールも進化せず最新のnodeでは動かないものまででている。
さすがに困ったので、
swaggerを使うことにしたのだが、
こちらも何か良くなったのかと言えば、
現状も変わってないようだ。
(-_-;) めんどい
YAML直接編集で仕様書書くとかやってられないし、
swagger editorも使い勝手が最悪だし。
何か良い方法はないかと探したら良いものがあった。
APIテストのGUIで仕様書を出力するツール。
これならまだ使えそうか。
ソースはGithubで管理しているので、
ドキュメントはmarkdownにしたい。
あと、見やすさを重視してHTML表示もしたい。
そのあたりもカバーしよう。
ヾ(・ω<)ﾉ" 三三三● ⅱⅲ コロコロ♪
------------------- ↓ 本題はここから ↓-------------------
事前準備
コマンドはnodeを使うのでnodejsやnpmが動くのが前提。
インストール
ホームページに行くとメアド入力を求められるが別に必要ない。
（メアド適当でもダウンロード画面出るけど。）
Githubから直接ダウンロードする。
以下の警告が出るが、
[詳細情報]-[実行]を押下
(野良アプリじゃないんだから、この辺ちゃんとして欲しいなぁ)
画面はPostmanなどのAPIテストツールのような感じ。
Pathを設定してパラメーターを定義する。
そうすれば自動的にOpenAPI定義ファイルが生成される。
Stoplight Studio UI
試しにAPIを作成した画面。
割と使いやすいUIかも。
HTML変換
HTML変換は見た目重視。
スタイルがいけてれば何でも言いかなと。
小生はRedoc推し。
インストール
適当なディレクトリにnpmコマンドでインストールを実行
(ついでに閲覧用のhttp-serverもインストール)
npm init -f # (package.jsonが無いとき)
npm i -D redoc-cli http-server
変換
適当なディレクトリに先ほど作ったサンプルAPIを変換
npx redoc-cli build reference/User.yaml -o dist/User.html
Redoc
(･∀･)素敵
Markdown変換
Markdown変換ツールはいくつか存在しているが、
筆者はwiddershinsを使っている。
詳細がしっかり書かれたmarkdownができあがる。
インストール
適当なディレクトリにnpmコマンドでインストールを実行
npm init -f # (package.jsonが無いとき)
npm i -D widdershins
変換
適当なディレクトリに先ほど作ったサンプルAPIを変換
mkdir dist
npx widdershins --omitHeader --code true reference/User.yaml dist/User.md
------------------- ↓ 後書はここから ↓-------------------
各種ツール
swaggerに変えてよかった点は、
サードパーティーツールが意外と充実していることだった。
swagger自体は基本使わないが、
OpenAPI仕様のツールは今後も使っていこうと思う。
以下はツール紹介だけ記載
モックサーバ Prism
Stoplightが提供しているモックサーバ。
OpenAPIは一応設計書なので、
そのままモックサーバの使用として利用できる。
npm i -D @stoplight/prism-cli # インストール
npx prism mock User.yaml # モック起動
リクエストはPostmanやPHPStorm、あるいは仮実装コードなどで。
OpenAPIバリデーション
手書きが基本のOpenAPIなので、
バリデーションツールは一応ある。
今回手書きでyaml生成していないので、
使うことはなかったが。
npm i -D @apidevtools/swagger-cli
npx swagger-cli validate User.yaml
OpenAPI3.1は未対応っぽい(令和４年８月２７日現在)
Yamlマージ
OpenAPI仕様に$refという参照機能がある。
これはリクエストやレスポンス、モデルなどを別ファイルなどで定義して、
仕様側では参照することで作成、メンテナンスの手間を省くことができる。
ただ、Redocなどツール側で別ファイルの参照に対応していないものもある。
そこで、いったん一つのファイルにマージして、
その後変換ツールに渡すためのマージツールというのがある。
npm i -D swagger-merger
npx swagger-merger -i in.yaml -o out.yaml
Postman to OpenAPI
stoplight studioではなくPostmanを使って手もあった。
ただ、リクエストは定義できるけど、
使用は定義できないなと見送った。
一応OpenAPIコンバートツールはあるみたい。
使ったこと無いので使用感はわからない
Discussion