Edited at

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

More than 3 years have passed since last update.


概要

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