Help us understand the problem. What is going on with this article?

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

More than 3 years have passed since last update.

概要

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

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

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

apiary_github_1.png

Apiaryでドキュメントを作成

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

GitHubと連携させる

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

apiary_github_2.png

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

apiary_github_3.png

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

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

apiary_github_4.png

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

apiary_github_5.png

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

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

apiary_github_6.png

APIドキュメントの更新

ブラウザからの更新

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

apiary_github_7.png

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

apiary_github_8.png

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

apiary_github_9.png

ローカルでの更新

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

apiary_github_10.png

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

apiary_github_11.png

まとめ

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

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away