dackdive's blog

新米webエンジニアによる技術ブログ。JavaScript(React), Salesforce, Python など

apiary.apibを複数ファイルに分割&任意のディレクトリに置く方法

TL;DR

GitHub リポジトリを連携して Apiary.io を使っているとき、
以下のようにすると apiary.apib を複数ファイルに分割したり、好きなディレクトリの下に置いて管理することができる。が、非公式なので自己責任。

  • root ディレクトリに apiary.apib とともに apiary.manifest というファイルを作る
  • apiary.manifest には読み込みたい API ファイルを一行ずつ記述する
apiary.apib
sub/foo.apib
sub/bar/baz.apib
  • GitHub に push すると、apiary.manifest に書いた順番に中身を結合した状態でドキュメントに反映される

注意点

  • root ディレクトリの apiary.apib は必要
  • apiary client では apiary.apib しか認識してくれない
  • web サービスのエディタで編集すると、結合された状態の内容が apiary.apib に上書きされる

はじめに

最近 API ドキュメントの作成を補助してくれるようなツールを探していて
Apiary.io というツールを見つけて触ってみている。

このツールは自分の GitHub リポジトリと連携することができて
リポジトリの root ディレクトリに apiary.apib というファイルを置けば push したときに自動で web 上のドキュメントに反映させることができる。

できるんだけど、"root ディレクトリに apiary.apib という名前のファイルを置く" という制限に不便を感じていて

  • 機能ごとにドキュメントファイルを分割して複数ファイルで管理したい
  • ドキュメントファイルは root ディレクトリじゃなくて任意のディレクトリの下に置けるようにしたい
  • できれば任意の .apib ファイル名で管理したい

といった要望がある。

ので、調べてみた。

調べてみる

Apiary.io のサポートフォーラム(?) に要望としてあがっていて、
Apiary Help

なのでまだ複数ファイルには対応していないのかなと思ったらこんな記事を見つけた。
apiary.io - Apiary multiple blueprint file into one api - Stack Overflow

どうやら、

  1. apiary.manifest というファイルを root ディレクトリに置く
  2. apiary.manifest ファイルの中に、読み込ませたいファイルのパスを改行区切りで記述する

と複数ファイルの読み込みが可能らしい。

試してみる

検証のために GitHubリポジトリを 1 個作り(Apiary と連携済み)、ディレクトリ構成を以下のようにする。

(root ディレクトリ)
├── apiary.apib
├── apiary.manifest
└── sub
    └── api.apib

そして各ファイルの中身は以下のようにする。

GitHub に push した後、Apiary にアクセスすると

f:id:dackdive:20150705010448p:plain

こんな感じで sub/api.apib の内容が apiary.apib の後に続いて記述され、全体として 1 つのファイルとして認識されている。

ただし注意点として、apiary-client では対応していないらしく、一番上の apiary.apib しか認識してくれなかった。

$ apiary preview

f:id:dackdive:20150705011027p:plain