業務で必要に駆られてAPIリファレンスを作成することとなりまして、ググってみるとSwaggerとAPI Blueprintの記事がちらほら。
Qiita記事を漁りながらSwaggerから触ってみましたが、なかなか取っ付きづらかったのと、自身がYAML触り慣れていないのでしっくりきませんでした。
API Blueprintを触ってみたら、よく使っているMarkdown記法で書けるということで導入しやすかったので、 API Blueprintを使ってリファレンスを書いてみることにしました。
API Blueprintとは
API Blueprint は Web API の仕様を表現するためのツールです。別のツールとして先述している「Swagger」や「RAML」というものがあります。 API の仕様を表現するための様々な文法を持っています。API Blueprintの 書き方は Markdown と同じ形式なので、非常になじみやすいかと思います。
こんなAPIのリファレンスドキュメントを書きたい 書き方がどう、というよりサンプルを解説したいと思います。
まず、下記のような仕様のWebAPIを作成しようとします。
仕様：
- ユーザ情報の登録を行えること。登録するデータは名前・性別・年齢・血液型。JSON形式で登録する。
- ユーザ情報の参照を行えること。参照するデータはURI パラメータで指定できること。
- ユーザ情報の変更を行えること。変更するデータはURI パラメータで指定できること。変更内容はJSON形式で登録する。
- ユーザ情報の削除を行えること。削除するデータはURIパラメータで指定できること。 さて、API Blueprintで書き表すと次のような感じになります。
API Blueprintだとこんな書き方になる はい！どーーーーーーーん！！
FORMAT: 1A # ユーザ管理API ## ユーザ情報登録 [POST /vi/user/] ユーザ情報の登録を行えること。登録するデータは名前・性別・年齢・血液型。JSON形式で登録する。 + Request (application/json) + Attributes (UserInfoData) + Response 200 (application/json) + Attributes (object) + user_id: 1 (number) - ユーザID + Response 400 (application/json) + Attributes (InvalidError) + Response 500 (application/json) + Attributes (ServerError) ## ユーザ情報参照 [GET /vi/user/{user_id}] ユーザ情報の参照を行えること。参照するデータはURI パラメータで指定できること。 + Parameters user_id: 1 (number, required) - ユーザ情報参照対象のユーザID + Response 200 (application/json) + Attributes (UserInfoData) + Response 404 (application/json) + Attributes (NotfoundError) + Response 500 (application/json) + Attributes (ServerError) ## ユーザ情報登録 [PUT /vi/user/{user_id}] ユーザ情報の変更を行えること。変更するデータはURI パラメータで指定できること。変更内容はJSON形式で登録する。 + Parameters user_id: 1 (number, required) - ユーザ情報変更対象のユーザID + Request (application/json) + Attributes (UserInfoData) + Response 200 (application/json) + Response 400 (application/json) + Attributes (InvalidError) + Response 404 (application/json) + Attributes (NotfoundError) + Response 500 (application/json) + Attributes (ServerError) ## ユーザ情報登録 [DELETE /vi/user/{user_id}] ユーザ情報の削除を行えること。削除するデータはURIパラメータで指定できること。 + Parameters user_id: 1 (number, required) - ユーザ情報削除対象のユーザID + Response 200 (application/json) + Response 404 (application/json) + Attributes (NotfoundError) + Response 500 (application/json) + Attributes (ServerError) ## Data Structures ### UserInfoData + user_name: サンプル太郎 (string, required) - 名前 + gender: 男性 (enum[string], optional) - 性別 + Members + 男性 + 女性 + age: 20 (number, optional) - 年齢 + blood_type: A (enum[string], optional) - 血液型 ### InvalidError + msg: Invalid Reqest Paramater . (string) - メッセージ + error_type: Invalid Error (string) - エラータイプ ### ServerError + msg: Connection failed. (string) - メッセージ + error_type: ServerError (string) - エラータイプ ### NotfoundError + msg: USER ID 15 is not found. (string) - メッセージ + error_type: NotFound Error (string) - エラータイプ
こんな感じです。
Markdownで普段メモとったりドキュメント書いてるひとは、馴染みやすいのではないでしょうか？
カッチョいい見た目にするためにRendererを使って変換する
このままのMarkdown形式のままだと
APIリファレンスっぽくないので、aglioというRendererを使います。
インストール方法
npmパッケージなので、npm installでインストールを行うことができます。
npm install -g aglio
インストールできたかコマンドを実行して確認してみます。
aglio Usage: aglio [options] -i infile [-o outfile -s] Options: -i, --input Input file -o, --output Output file -t, --theme Theme name or layout file [default: "default"]
使い方
使い方はAPIリファレンスファイル（HTML）の生成 APIリファレンスドキュメントサーバの起動 の2通りあります。
APIリファレンスファイル（HTML）の生成
markdownで書いたAPI BlueprintなファイルをHTML形式に変換します。
aglio -i <src_file> -o <dst_file>
上記コマンドを実行すると
src_fileで指定したファイルをdst_fileに出力します。
配布用に出力するときに使うことが多いと思います。
APIリファレンスドキュメントサーバの起動
APIリファレンスドキュメントをファイルではなく、Webサーバ上に立てることができます。
aglio -i <src_file> --server
デフォルトではPort 3000番を使用して起動します。
http://localhost:3000へアクセスすることで、Webブラウザ上でAPIリファレンスを確認することができます。見た目少し立地にしてみましたが
--portオプションを使用することでPort指定して起動することもできます。
例： aglio -i <src_file> --server --port 3003 変換結果
変換すると以下のような画面を生成することができます。
まとめ
Swagger、RAMLをちゃんとさわれていないので、API Blueprintだけをベタ褒めしたらいけないと思いますが、 モダンなAPIリファレンスを作るのであれば、 Markdownで書けるAPI Blueprintが学習コストが少なくて良いと思いました。
今回のサンプルソースと変換後のHTMLファイルはGitのほうにあげておいたので、気になるかたは見てみてください。
