こんにちは。エンジニアの原です。
突然ですが、仕様書の管理ってしんどいですよね。
ないと困るのはわかっていても、いざ作るとなるとどうも気が乗らない。
Excel や Word のなどを使って作ってしまうと、変更があったときに
どこに変更があったのかわかりにくかったりします。
やっぱり履歴を持つようなファイルは Git 管理がしたいですよね。
というわけで、今回は「 Git 管理できる仕様書を作成しよう」をテーマに、
API Blueprint の紹介をしたいと思います。
API Blueprintとは
API Blueprint とは Web API の仕様を表現するための言語のことです。
API Blueprint 公式ページ
API の仕様を表現するための様々な文法を持っています。
書き方は Markdown と同じ形式ですので、書き方も馴染みのあるものです。何よりただのテキストファイルですので、Git などのバージョン管理ツールを使えば、変更内容の差分を確認したりすることができます。
また、API Blueprint は周辺ツールが揃っていてるのも特徴です。
API Blueprint を使って API の仕様書を書いておけば、仕様書を元に API のモックを作ったり、HTML での仕様書出力ができたりします。
今回は、API Blueprint の基本と HTML 仕様書出力ツール Aglio を使った仕様書の HTML 出力を説明します。
文書構造
まずはじめに、API Blueprint の文書構造について説明します。
API Blueprint では # 記号を使って階層を分けています。階層は以下のようになっています。
# リソースグループ
一番上の階層は、API のグループです。
関連する API を一つのグループとして管理します。
例外として、仕様書の最初の # は、仕様書のタイトルとして使用されます。
## リソース
APIのエンドポイント毎の階層です。
### アクション
各エンドポイントでなにができるかを記述する階層です。
HTTPメソッド毎にアクションを書いていきます。
API Blueprint サンプル
早速ですが、実際に API Blueprint を使って仕様書を書いてみましょう。まずはサンプルを示します。
FORMAT: 1A
HOST: http://example.com
# 物品情報管理
会社の物品貸出の情報を扱う API です。
# 本
## 基本情報 [/book{?id}]
本の基本情報を扱います。
### 基本情報取得 [GET]
本の基本情報を取得します。
+ Parameters
+ id: `0001-0001-0001` (string, required) - 物品ID
+ Response 200 (application/json)
+ Attribute
+ id: `0001-0001-0001` (string, required) - 物品ID
+ title: `プログラミングができる本` (string, required) - 物品名
+ Response 404 (application/json)
+ Attribute
+ message: `404 Not Found` (string, required) - エラーメッセージ
### 基本情報登録 [POST]
本の基本情報を登録します。
+ Request
+ Attribute
+ id: `0001-0001-0001` (string, required) - 物品ID
+ title: `プログラミングができる本` (string, required) - 物品名
+ Response 200 (application/json)
+ Attribute
+ id: `0001-0001-0001` (string, required) - 物品ID
+ title: `プログラミングができる本` (string, required) - 物品名
+ Response 503 (application/json)
+ Attribute
+ message: `Internal Server Error` (string, required) - エラーメッセージ
ひとつずつ確認していきましょう。
メタデータ
FORMAT: 1A HOST: http://example.com
仕様書の先頭には、仕様書に関するメタデータが書けます。
FORMAT は API Blueprint のバージョンを示しているもので、2017年1月25日では 1A のようです。HOST には API サーバの HOST を書きます。
HOST はあとで Aglio を使って出力する HTML 仕様書のベース URL に反映されます。
タイトル
# 物品情報管理 会社の物品貸出の情報を扱う API です。
最初の記述した # なので仕様書のタイトルになります。
リソースグループ
# 本
リソースグループです。
サンプルでは本としました。他には文房具や電子機器などが考えられます。意味のある単位で分けていきましょう。
リソース
## 基本情報 [/book{?id}]
本の基本情報を扱います。
API のエンドポイントの情報です。 {?parameter} と書くことで、URI パラメータを書くことができます。
アクション
### 基本情報取得 [GET]<br />
本の基本情報を取得します。</p>
+ Parameters<br />
+ id: `0001-0001-0001` (string, required) - 物品ID
+ Response 200 (application/json)
+ Attribute
+ id: `0001-0001-0001` (string, required) - 物品ID
+ title: `プログラミングができる本` (string, required) - 物品名
+ Response 404 (application/json)
+ Attribute
+ message: `404 Not Found` (string, required) - エラーメッセージ
アクションには、リクエストやレスポンスの情報を書きます。
サンプルでは、本の基本情報を取得する GET リクエストを用意しました。Parameters には URI パラメータをリストで書きます。書き方はなんとなくわかるかと思いますが、以下のようになっています。
+ <パラメータ名>: <例> (型, 必須かどうか) - 説明文
Response はステータスコード毎に複数書ける様になっていて、書き方は Parameters と同様です。
Data Structureとは
API Blueprint では Data Structure を使って複数のパラメータをひとつものとして定義できます。
リクエストやレスポンスに、繰り返し出現するデータが存在するのはよくあることです。
そのたびに同じことを繰り返し書くと手間ですし、少し修正が入った際にすべての箇所に
変更を加えるとなると、変更漏れが生じて仕様の整合性が取れなくなる可能性もでてきます。
先ほどのサンプルを見てみましょう。
サンプルで扱っている本の基本情報は、ID とタイトルしかありません。もっと多くの情報を扱える様にしたいと思うのですが、今の書き方だと、基本情報取得 API レスポンスや基本情報登録 API のリクエストなど、本の基本情報に関する記述が散らばってしまっています。 基本情報取得 API レスポンスは修正したのに、基本情報登録 API のリクエストの修正を忘れていた、なんてことは避けたいですよね。
そんなときは Data Structure が使えます。
# Data Structure ## Book + id: `0001-0001-0001` (string, required) - 物品ID + title: `プログラミングができる本` (string, required) - 物品名
このように Data Structure として Book を登録しておけば、仕様書の他の箇所で Book を参照できるようになります。それぞれの箇所で Book を記述するのではなく、Book の記述は Data Structure の一箇所にまとめ、他の箇所では Book を参照する様にします。こうすることで、本の基本情報にカテゴリを追加したい場合は、Data Structure に追加するだけでよくなります。
サンプルで使用してみると下記のようになります。
### 基本情報取得 [GET]
本の基本情報を取得します。
+ Parameters
+ id: `0001-0001-0001` (string, required) - 物品ID
+ Response 200 (application/json)
+ Attribute(Book)
+ Response 404 (application/json)
+ Attribute<br />
+ message: `404 Not Found` (string, required) - エラーメッセージ
### 基本情報登録 [POST]
本の基本情報を登録します。
+ Request
+ Attribute(Book)
+ Response 200 (application/json)
+ Attribute(Book)
+ Response 503 (application/json)
+ Attribute
+ message: `Internal Server Error` (string, required) - エラーメッセージ
# Data Structure
## Book
+ id: `0001-0001-0001` (string, required) - 物品ID
+ title: `プログラミングができる本` (string, required) - 物品名
変更が生じたときは、Book を一回変えるだけでよくなりました。
Aglio を使ったHTML出力
API Blueprint は Web API の仕様を記述するためのものですが、そのままのテキストでは必ずしも読みやすいとは言えません。API Blueprint で記述した仕様書を、もっと読みやすい形式に出力してみましょう。
Aglio を使うと、API Blueprint で書いた仕様書を HTML ファイルとして出力できます。npm コマンドを使ってすぐにインストールできます。
npm install -g aglio
使い方も簡単で、API Blueprint で記述した仕様書ファイルと出力するファイル名を指定してコマンドを打つだけです。
aglio -i <入力ファイル名> -o <出力ファイル名>
上記のサンプルで出力してみたファイルは以下のようになっています。
終わりに
今回は API Blueprint による Web API 仕様書作成についてまとめさせていただきました。
API Blueprint の周辺ツールは Aglio 以外にもたくさんあります。
次に仕様書を書くときは是非試してみてください。
フェンリルのオフィシャル Twitter アカウントでは、フェンリルプロダクトの最新情報などをつぶやいています。よろしければフォローしてください！
関連記事
