API BlueprintでWeb APIのドキュメントを生成する

## 概要

この記事ではAPI Blueprint形式でWeb APIの仕様をMarkdownっぽく記述しつつ、aglioで自動的にドキュメント化してみます。

## インストール
まずHomebrewでnode.jsをインストールして、npmからaglioのパッケージをインストールします。

```sh
# node.jsおよびnpm導入の参考例
$ brew install node
$ npm install -g aglio
```

## (前準備)ダミーのWeb APIを用意する

前準備として、まずはドキュメントを書く対象となる適当なWeb APIを用意します。ここではサンプルとして、以下のサイトに掲載されているPythonのBottleというパッケージで書かれたダミーのRESTful APIを返すサーバを使ってみましょう。

- [Creating a RESTful Python API with Bottle - Fabrizio (Fritz) Stelluto](http://gotofritz.net/blog/weekly-challenge/restful-python-api-bottle/)

このサイトの`bottle/test2.py`は、最低限のCRUD操作が備わったWeb APIを提供するコードです。それぞれレシピのXMLのパスが返ってきたり、レシピを投稿したり削除する機能を模していますが、実際のコードでは単にテンプレのjsonを返すだけのものです。

- http://localhost:8080/recipes：GET
- http://localhost:8080/recipes/name：GET
- http://localhost:8080/recipes/name：PUT
- http://localhost:8080/recipes/name：DELETE


## API Blueprint形式のMarkdownを記述する

さて、実際にAPI Blueprintを使ってWeb APIの構造を記述していきましょう。まずは`http://localhost:8080/recipes`にGETでアクセスすると、すべてのレシピのXMLが返ってくるWeb APIの仕様を書いてみます。

なお、詳細なAPI Blueprintの記法等は公式ドキュメントやチュートリアルを参考にして下さい。

```markdown
FORMAT: 1A

# レシピサイトWebAPIドキュメント

## すべてのレシピのXMLを表示する [/recipes]

### recipes_list [GET]
すべてのレシピのリストを返します。

+ Response 200 (application/json)
    + Attributes
        + success: False (boolean) - ステータス
        + path (array) - XMLファイルパス
        + error: show not implemented yet (string) - エラーメッセージ

```

まず1行目ではWeb APIのメタ情報としてバージョン情報を記述しています。

2行目以降では、Markdownと同様に見出しと、それに対応するURLやHTTPメソッドの種類を記述しています。これは後のaglioでドキュメント化するときのためのものです。

そして`+ Response 200 (application/json)`行以降では、具体的にどのようなWeb APIなのかを記述しています。これはMarkdownを拡張した[MSON](https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md)という記法を使って書かれています。ここにレスポンスで返ってくるjsonをそのまま貼り付けることも可能ですが、可読性や変更のしやすさを考えるとMSON記法の方が良さそうです。

さて、このような形式でその他3つのWeb APIについても記述をしていきます。完成版はGistに上げておきました（[recipe.apib](https://gist.github.com/yagays/af69766e1b1e6acb595bf4bfe528079d)）。

## aglioでドキュメントをHTML形式で出力する

API Blueprint形式でWeb APIの構造が記述できたところで、これを                                             [aglio](https://github.com/danielgtaylor/aglio)を使って見やすいドキュメントに整形します。

```sh
$ aglio -i recipe.apib -o recipe.html 
```

aglioで作成した`recipe.html`を開くと、以下ようなHTML形式のドキュメントが表示されます。それぞれのWeb APIのレスポンスに加え、JSON Schemaも表示されます。

<img width="1000" alt="ss 2016-04-21 0.53.22.png" src="https://qiita-image-store.s3.amazonaws.com/0/4452/65098df2-261c-fb29-a031-7c606ee5e513.png">


なお、aglioでは幾つかのHTMLのテンプレートが用意されており、two columnとthree columnといった表示形式を選択したり、テーマ自体を変更することができます。

```sh
$ aglio -i recipe.apib -o recipe.html --theme-variables slate --theme-template triple
```

<img width="1261" alt="ss 2016-04-21 2.17.43.png" src="https://qiita-image-store.s3.amazonaws.com/0/4452/bce93543-bdc6-af4c-8cb2-5c6e999d081c.png">

## まとめ

このように、API Blueprint形式のドキュメントを書くだけで、aglioで綺麗なHTML形式のドキュメントを生成することができました。Web APIのドキュメントをテキスト形式で管理できるのでgitなどのバージョン管理との親和性も高いですし、Web APIのスキーマを設計しながらドキュメントも同時に書き進められるのではないかと思います。

一方でデメリットは各所で言われているように、API BlueprintやMSONの形式には癖があって、記法に慣れるのに少し時間は掛かるかもしれません。その辺りは少し我慢をしてサンプルを見つつ頑張って書くほかに、ApiaryというGithubと連携したドキュメント生成のウェブサービスに[Apiary Editor](https://help.apiary.io/tools/apiary-editor/)というエディタが付属しているので、そちらを利用する手もあります。

## 参考

- 公式チュートリアル系
  - [API Blueprint tutorial | Apiary Help](https://help.apiary.io/api_101/api_blueprint_tutorial/)
  - [API Blueprint Tutorial | API Blueprint](https://apiblueprint.org/documentation/tutorial.html)
- [API Blueprint で Web API の仕様を書く - CUBE SUGAR CONTAINER](http://blog.amedama.jp/entry/2016/03/08/202403)
- [APIの仕様をMarkdownで定義する - HDE BLOG](http://blog.hde.co.jp/entry/2015/01/16/152729)
- [APIドキュメントを生成するためのMarkdown拡張API BluePrintとその周辺のライブラリ - Qiita](http://qiita.com/taizo/items/0181f5ea641e2f91d0a5)
- [APIドキュメントを支える技術 - Qiita](http://qiita.com/taizo/items/5a969ace57394a2d5b4a)
	- swaggerやJSON Schemaなど他の技術との比較