TL;DR
GitHub リポジトリを連携して Apiary.io を使っているとき、
以下のようにすると apiary.apib
を複数ファイルに分割したり、好きなディレクトリの下に置いて管理することができる。が、非公式なので自己責任。
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
どうやら、
apiary.manifest
というファイルを root ディレクトリに置くapiary.manifest
ファイルの中に、読み込ませたいファイルのパスを改行区切りで記述する
と複数ファイルの読み込みが可能らしい。
試してみる
検証のために GitHub のリポジトリを 1 個作り(Apiary と連携済み)、ディレクトリ構成を以下のようにする。
(root ディレクトリ) ├── apiary.apib ├── apiary.manifest └── sub └── api.apib
そして各ファイルの中身は以下のようにする。
GitHub に push した後、Apiary にアクセスすると
こんな感じで sub/api.apib の内容が apiary.apib の後に続いて記述され、全体として 1 つのファイルとして認識されている。
ただし注意点として、apiary-client では対応していないらしく、一番上の apiary.apib
しか認識してくれなかった。
$ apiary preview