API BlueprintでAPI仕様書を書く
ツールが古すぎるのが玉に瑕
関連記事:
SwaggerでOpenAPI仕様書を作成、HTMLやMarkdownに変換する
みんな大好き仕様書の話
最近のサーバーサイドエンジニアはフロントAPIを作るのがメインの作業になってることが多い。
フロントはReactやVueだったりスマフォアプリだったり。
で、フロント側のエンジニアと会話をするときに必要なのがAPI仕様書。
箇条書きとかAPIの説明書などではAPIの中身はわかっても最終的にどういうデータが取れるかがわからない。
(口頭は論外)
そこでAPI仕様書を起こして入力値、出力値(型やフォーマットなども)を明確にする。
LaravelなどではLaravel API Documentation Generatorのようなコメントアウトに記述するタイプもあるが、
コードのコメントアウト部分が重たくなってコードが見辛くなる。
API仕様書で調べるとswaggerがまず見つかると思う。
API設計から仕様書策定、テスト、モックサーバーなど多機能ツールとなっている。
ただ、個人的には重厚すぎて扱いたくないレベル。
などもあるが、
それはまたの機会にし、
今回はAPI Blueprintで仕様書を作成していく。
以下のような特徴がある
- Markdown記法
- ドキュメント生成
- モックサーバー機能
- APIテスト機能
機能的には十分。
ただ、Oracleが買うと進化が止まる法則があって、
五年ぐらい進化していないところが残念。
あと、JsonAPIが前提の使用になっていて、
ちょっと変わったことをしようとすると苦労する。
ヾ(・ω<)ﾉ" 三三三● ⅱⅲ コロコロ♪
------------------- ↓ 本題はここから ↓-------------------
事前準備
ツールのインストール
npm i aglio drakov dredd
VSCode
VSCodeにAPI Blueprint用のプラグインがあるので、
それらをインストール
- API Elements extension
- API Blueprint Viewer
仕様書生成の流れ
仕様書作成
まずは簡単なクエリストリング付きGETリクエストを使って仕様書を書いてみる
拡張子 .apib のファイルを作成しマークダウン記法で記述する。
こんな感じのリクエストの場合
/message?page=2&limit=15
FORMAT: 1A
# API Blueprint
## ハロー・ワールド API
# Echo Hello [/message{?page,limit}]
## ハロー・ワールド取得API [GET]
+ Parameters
+ page: 2 (number, optional) - ページ数
+ limit: 15 (number, optional) - 取得件数
+ Default: `20`
+ Response 200 (text/plain)
Hello World!
(･ω･) クエリストリングの書き方が独特だなぁ。
ドキュメント生成
さて仕様書が書けたところで、
次は閲覧しやすいようにHTMLに変換する。
使用するツールはaglio。
npx aglio -i hello.apib -o hello.html
ドキュメント生成すると以下のような感じ
(･∀･) 見やすい!
モックサーバー起動
ドキュメント作成目的だけでも十分だが、
他にも使い道がある。
その一つがモックサーバー機能で、
これは簡易の入出力サーバーと言えば良いか。
先ほど作成した仕様書通りのリクエストを投げると、
仕様書記載の通りの返答をしてくれる。
これを使ってAPIが実装前でもAPIを使用する前提のシステム構築を並行して行うことができる。
モックサーバー機能のツールはdrakov
npx drakov -p 3002 -D 1 -f hello.apib
[INFO] No configuration files found
[INFO] Loading configuration from CLI
DRAKOV STARTED
[LOG] Setup Route: GET /message ハロー・ワールド取得API
Drakov 2.0.1 Listening on port 3002
サーバー起動した状態でcurlを叩いてみると
curl localhost:3002/message -H 'Content-Type: text/plain'
Hello World!
(･∀･)」仕様書通り！
APIテスト実行
実際にリクエストを投げてテストを実行する機能。
使うツールはdredd。
先ほどのモックサーバーを起動したまま以下のコマンドを実行してみると
npx dredd .\hello.apib http://localhost:3002
(node:8336) Warning: Accessing non-existent property 'padLevels' of module exports inside circular dependency
(Use `node --trace-warnings ...` to show where the warning was created)
fail: GET (200) /message?page=2&limit=10 duration: 111ms
info: Displaying failed tests...
fail: GET (200) /message?page=2&limit=10 duration: 111ms
fail: headers: At '/content-type' No enum match for: "text/plain; charset=utf-8"
戻り値が text/plain じゃなくて text/plain; charset=utf-8 が返ってきてるってエラー。
(･ω･) 細かいなぁ・・・。
上記エラーに基づいて仕様書を調整
- + Response 200 (text/plain)
+ + Response 200 (text/plain; charset=utf-8)
他にもPOSTやPUTなどの別のリクエスト、
HTTP Form、json API、JSON-Rpcなど様々なスタイルに対応できそう。
記述方法は別記事にしようと思う。
------------------- ↓ 後書はここから ↓-------------------
冒頭に書いたが、
aglio, drakov, dreddともに更新が止まっている。
aglioに至っては5年前で止まっている。(令和4年2月23日現在)
仕様が進化しなければ、
やることは大きく変わらないので、
ツールが進化しないのも仕方が無いが、
nodeのバージョンが新しいと、
インストールが難しくなる問題がでてくる。
最近ではdocker経由で使用する例も増えているようだ。
ツールはもう少し深掘りが必要かもしれない。
swaggerを使う
(令和４年９月１４日追記)
流石にツールが古くなりすぎたので、
改めて仕様書を書く方法考えた。
Discussion