APIドキュメントというか定義はAPI Blueprintで書き、aglioならびにgulp-aglioを使ってhtml化をすると楽だよ的なお話

まんまタイトル通り。
API定義は人によって色々と書き方もあるだろうし、なんならAPIクライアントを使ってそこで管理するとかそういう方法もある。
特にAPIクライアントはPawみたいな便利なものもあるわけで。
ただ便利だからこそ有料だったり、チーム間で共有するにはさらにお金が必要だったり。
そうなるとかなり面倒だし、どちらかというとリファレンスだけ管理できればいいんだけどっていうケースは意外と多い。

ということで今日はある意味省エネな感じでAPIの定義をしてリファレンスを作ろう的なお話をば。

ちなみにAPI Blueprint(apib)はAPIをmarkdownで書いちゃおう的なやつ。
似たようなものとしてはswaggerっていうのがあって、実はAWSのAPI Gatewayはswaggerからのインポートにも対応していたり。
けど個人的にあまり好きじゃないのもあってAPI Blueprintを押していきたい。

で、とりあえずのところしては、API Blueprintで書き、それをaglioを使ってhtml化をするリポジトリを作った。
これを見てもらえればわかりやすいんじゃないかと。

■ディレクトリ構成

.
├── README.md
├── apib
│   ├── index.md
│   ├── login.md
│   └── user.md
├── gulpfile.js
└── package.json

apibというディレクトリ内にはindex.mdとその他のmdファイルがある。
index.mdでAPIの名前とHOSTとか大まかな説明をし、さらにその他のmdファイルをインポート。
ちなみにその他のmdファイルはGroup単位で区切る形になるので、ユーザ用のAPiに関してはuser.mdみたいな。

ってな感じでやってあげ、gulp buildをするとdistというフォルダができるので、それをローカルで開けばOK。

ちなみにファイルをGroup単位で分割する理由としては、一つのファイルで管理するのは面倒だし、
チームで開発するとなるとAPIも細かく分割されるはずだろうからっていう感じで。
ただ閲覧するときは一つのファイルにしたいからインポートして一つのファイルにしましょう的な。

で、これを先日書いたgithubのリポジトリ整理の記事のサービス名リポジトリの中にschemaとして入れてあげれば、
そのサービスに関わっている人全員がAPIのschemaを見れるし管理できるという感じでいいんじゃないかと。

ってな感じでAPIを管理してあげればいいんじゃないかと。
特に前回の記事と合わせてAPI定義も管理しやすくなるし、markdown形式だから記入も慣れれば簡単なわけで。
仕様とかを統一するにはこういう形が一番いいと思うよ的なみたいな。