API Blueprint
Swaggerに代表される、APIドキュメントを生成する環境です。
Markdown形式で記述したあと、aglioというコマンドを叩くと単一のHTMLファイルを生成してくれるため、サクッと始めるにはちょうどいい方式です。
quickstart
sampleを生成するところまでを説明します。
sample
以下のガイドに従って、sample.apibファイルを作成します。
cf. https://apiblueprint.org/documentation/examples/01-simplest-api.html
sample.apib
FORMAT: 1A
# The Simplest API
This is one of the simplest APIs written in the **API Blueprint**. One plain
resource combined with a method and that's it! We will explain what is going on
in the next installment -
[Resource and Actions](02.%20Resource%20and%20Actions.md).
**Note:** As we progress through the examples, do not also forget to view the
[Raw](https://raw.github.com/apiaryio/api-blueprint/master/examples/01.%20Simplest%20API.md)
code to see what is really going on in the API Blueprint, as opposed to just
seeing the output of the Github Markdown parser.
Also please keep in mind that every single example in this course is a **real
API Blueprint** and as such you can **parse** it with the
[API Blueprint parser](https://github.com/apiaryio/drafter) or one of its
[bindings](https://github.com/apiaryio/drafter#bindings).
# GET /message
+ Response 200 (text/plain)
Hello World!
install agrio
agrioというツールでHTMLを生成します。
npm経由でinstallすることができます。
cf. https://www.npmjs.com/package/aglio
sudo npm install -g aglio
HTML生成
以下のコマンドで生成が可能です。
-iでinput、-oでouputを指定します。
$ aglio -i sample.apib -o sample.html
以下のように出力されます。
ファイル分割
<!-- include(hoge.apib) -->のように参照することでファイル分割が可能です。
index.apib
FORMAT: 1A
<!-- include(users.apib) -->
<!-- include(items.apib) -->
users.apib
# Group User
## GET /api/v1/users
+ Response 200 (application/json)
Hello User!
items.apib
# Group Item
## GET /api/v1/items
+ Response 200 (application/json)
Hello Item!