概要
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レスポンスのテストが出来ると考えられるので、引き続き調べようと思います。