のうない あうとぷっと。
技術

APIリファレンスを作るためにAPI Blueprintを使ってみた

業務で必要に駆られて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のほうにあげておいたので、気になるかたは見てみてください。

sample.md

sample.html