aglioとは

既定の書き方で書かれたマークダウンファイルを、良い感じのAPIドキュメントに仕上げてくれるnodeのパッケージ。

aglioの記法

API Blueprint という規格に従って、mdファイルを書く。 https://apiblueprint.org/

実際にやったプロジェクト内での実装

aglioを直呼びするのは面倒かつ、いちいちaglioをインストールしてもらうのも面倒なので、gulpからaglioを呼んで、対象となるmdファイルをすべてまとめてhtml化している。

gulp.task('docs', () => {
  gulp.src(['src/*.md'])                  //1. srcフォルダ内のすべてのmdファイルを
    .pipe(concat('all_ref.md'))           //2. all_ref.mdに結合させて、
    .pipe(aglio({ template: 'default' })) //3. aglioに食わせてhtml化させて、
    .pipe(gulp.dest('docs'));             //4. docsフォルダ内にhtmlとして出力する
});

そもnodeをインストールするのが面倒という部分もなきにしもあらずですが、結局プロジェクト本体でnodeを使ってるしいいかな、という感じでガンガン使ってます。

実際に生成する

前提として、node.jsとgitのインストールを済ませているPCで行うこととします。

# console

> cd path/to/apidoc/root
> git clone https://hogehoge/fugafuga/git/repository.git
> npm install
> gulp docs

書いててハマったところ

階層を構成する空白

mdファイルでの階層を作るための文頭に置く空白文字は、半角スペース4つでないとaglioに食わせてもいい感じにhtml化してくれない模様。

#### 処理概要
* hogeの一覧を取得する。

+ Response 200 (application/json)
    * adm_divs内にはすべてのProvinceオブジェクトが格納される。 //←文頭はスペース4つ
    ```js
    {
        hoge_code   : {string} - hogeのコード。数字によって構成される。
        hoge_name   : {string} - hogeの名称。
    }
    ```

ResponseのAttribute記述時、array内のobjectに対し、説明文がつかない。

+ Response 200 (application/json)
    ```js
    {
        hoge_code    : {string} - hogeのコード。2桁の数字によって構成される。
        fuga_code    : {string} - fugaのコード。2桁の数字によって構成される。
        piyo_code    : {string} - piyoのコード。2桁の数字によって構成される。
        hoge_name    : {string} - hogeの名称。
        fuga_name    : {string} - fugaの名称。
        piyo_name    : {string} - piyoの名称。
    }
    ```
    + Attributes
        + fugas (array, required)
            + (object)
                + hoge_code : 01 (string) - こういう風に半角ダッシュ以降に説明文を書くと
                + fuga_code : 02 (string) - 良い感じにhtml化してくれそうだが、
                + piyo_code : 03 (string) - 実際には半角ダッシュ以降の説明文はhtmlには記載されない。
                + hoge_name : hoge name (string) - そのため、苦肉の策として、
                + fuga_name : fuga name(string) - Attribute以前に内部オブジェクトの情報を
                + piyo_name : piyo name(string) - コードブロックとして記述するようにしている。
            + (object)
                + hoge_code  : 01 (string)
                + fuga_code  : 02 (string)
                + piyo_code  : 03 (string)
                + hoge_name  : hoge name(string)
                + fuga_name  : fuga_name (string)
                + piyo_name  : piyo_name(string)

親愛なるジョンからの手紙

雑記です。ゲームとか漫画とかプログラミングとか。

aglio使ってAPIドキュメント書いたら捗った話と、書いててハマったところのまとめ