Apiaryで作成するAPIドキュメントをGitHubで管理する

概要

ApiaryでAPIドキュメントを作成した場合、そのドキュメント自体のバージョン管理をどうするか疑問でした。調べてみると、ApiaryにはGitHubと連携させることでドキュメントのバージョン管理を行う機能が用意されていたので、実際に試してみました。

サンプルリポジトリの作成

ApiarySmapleというリポジトリを作成します。

Apiaryでドキュメントを作成

Apirayでサンプルドキュメントを作成します。

GitHubと連携させる

ApiaryのメニューからSettingsを選択。

設定メニューの下部にGitHubとの連携についての説明が書いてあるので、「Connect to GitHub」をクリック。
今回はPublicでサンプルリポジトリを用意したので、 Grant access to my private repositories as well. にはチェックを付けません。

対象となるリポジトリを選択

GitHubとの連携を行うと、以下のように設定メニュー下部にリポジトリを選択する画面が表示されるので、先ほど作成したApiarySmapleを選択。

選択をすると以下のようになります。

リポジトリへのAPI Blueprintファイルの追加

ApirayでAPIドキュメントを作成する場合、API BlueprintというMarkdownを拡張した言語で記述します。拡張子は.apibです。上記でリポジトリを選択すると、ApiarySmapleリポジトリにapiary.apibがApiaryからプッシュされ自動的に追加されます。このファイルは、Apiaryのエディタで編集したものと同一のものになります。

APIドキュメントの更新

ブラウザからの更新

Apiaryへアクセスし、エディタでAPIドキュメントを更新します。通常は「Save & Publish」になっている右上のボタンがGitHubと連携済みの場合「Save & Commit」に変化します。

「Save & Commit」をクリックするとコミットメッセージの入力フォームが出てくるので、「test」と入力し、「Save and Push to GitHub」をクリックします。

GitHubを確認すると更新が反映されていることがわかります。

ローカルでの更新

ApiarySmapleをcloneし、apiary.apibを編集します。

編集後コミットしGitHubへプッシュすると、ApiaryのAPIドキュメントに自動的に反映されます。

まとめ

Apiaryで作成したAPIドキュメントをGitHubで管理することができました。さらにDreddを使うことで、.apibファイルを使用したAPIレスポンスのテストが出来ると考えられるので、引き続き調べようと思います。