dackdive's blog

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

follow us in feedly

API Blueprintによるドキュメント開発環境【2016年冬】

ここから少しアップデートしたのでメモ。

リポジトリ


特徴

markdown -> html への変換には aglio、ローカルサーバーは --server オプションを使う

ローカルで markdown ファイルを html に変換するのに aglio を使うところは以前と同じ。
改めて調べてみると、--server というオプションでライブリロード機能つきのローカルサーバーの起動までやってくれるらしく、browserSync は不要だった。

また、ポート番号については README に記載されていないが、-p オプションで指定できた。
参考:Support for different port? · Issue #12 · danielgtaylor/aglio

$ ./node_modules/aglio/bin/aglio.js
Usage: node_modules/aglio/bin/aglio.js [options] -i infile [-o outfile -s]

オプション:
  -i, --input           Input file
  -o, --output          Output file
  -t, --theme           Theme name or layout file        [デフォルト: "default"]
  -f, --filter          Sanitize input from Windows    [真偽] [デフォルト: true]
  -s, --server          Start a local live preview server
  -h, --host            Address to bind local preview server to
                                                       [デフォルト: "127.0.0.1"]
  -p, --port            Port for local preview server         [デフォルト: 3000]
  -v, --version         Display version number               [デフォルト: false]
  -c, --compile         Compile the blueprint file           [デフォルト: false]
  -n, --include-path    Base directory for relative includes
  --verbose             Show verbose information and stack traces
                                                             [デフォルト: false]
  --theme-variables     Color scheme name or path to custom variables
                                                         [デフォルト: "default"]
  --theme-condense-nav  Condense navigation links      [真偽] [デフォルト: true]
  --theme-full-width    Use full window width         [真偽] [デフォルト: false]
  --theme-template      Template name or path to custom template
                                                         [デフォルト: "default"]
  --theme-style         Layout style name or path to custom stylesheet
  --theme-emoji         Enable support for emoticons   [真偽] [デフォルト: true]

例:
  node_modules/aglio/bin/aglio.js -i        Render to HTML
  example.apib -o output.html
  node_modules/aglio/bin/aglio.js -i        Start preview server
  example.apib -s
  node_modules/aglio/bin/aglio.js           Theme colors
  --theme-variables flatly -i example.apib
  -s
  node_modules/aglio/bin/aglio.js           Disable options
  --no-theme-condense-nav -i example.apib
  -s

See https://github.com/danielgtaylor/aglio#readme for more information

(コマンド例)

$ aglio -i src/index.md -p 8080 --server


複数ファイルの分割は <!-- include(xxx.md) --> で実現

参考:https://github.com/danielgtaylor/aglio#including-files

エントリーポイントとなるファイルで

FORMAT: 1A

<!-- include(xxx.md) -->

としておくと、別のファイルを読み込むことができる。
これで API 定義を複数のファイルに分割することができる。

これ自体は以前調べたときにも把握はしてたようだが、モックサーバー用ライブラリ api-mock の制限で断念したようだった。
が、次に示すようにモックサーバを api-mock から drakov というライブラリに変更したのでこの問題は解決した。


モックサーバには api-mock のかわりに drakov を使用

以前調べたときは api-mock を使おうとしていたらしいが、
今 Node のバージョン 7.1.0、npm のバージョン 3.10.9 でインストールしようとしたところエラーになってしまった。

$ npm i -g api-mock
/usr/local/bin/api-mock -> /usr/local/lib/node_modules/api-mock/bin/api-mock

> protagonist@1.2.6 install /usr/local/lib/node_modules/api-mock/node_modules/protagonist
> node-gyp rebuild

  CXX(target) Release/obj.target/libmarkdownparser/drafter/ext/snowcrash/ext/markdown-parser/src/ByteBuffer.o
clang: error: invalid deployment target for -stdlib=libc++ (requires OS X 10.7 or later)
make: *** [Release/obj.target/libmarkdownparser/drafter/ext/snowcrash/ext/markdown-parser/src/ByteBuffer.o] Error 1
gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2
gyp ERR! stack     at ChildProcess.onExit (/usr/local/lib/node_modules/npm/node_modules/node-gyp/lib/build.js:276:23)
gyp ERR! stack     at emitTwo (events.js:106:13)
gyp ERR! stack     at ChildProcess.emit (events.js:191:7)
gyp ERR! stack     at Process.ChildProcess._handle.onexit (internal/child_process.js:215:12)
gyp ERR! System Darwin 14.5.0
gyp ERR! command "/usr/local/Cellar/node/7.1.0/bin/node" "/usr/local/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "rebuild"
gyp ERR! cwd /usr/local/lib/node_modules/api-mock/node_modules/protagonist
gyp ERR! node -v v7.1.0
gyp ERR! node-gyp -v v3.4.0
gyp ERR! not ok

この Issue が関係している?Node のバージョン 6 系からうまくインストールできないらしい。
install failed at protagonist package · Issue #53 · localmed/api-mock

しかたないので
https://apiblueprint.org/tools.html#mock-servers
の一番上にあった drakov にした。

drakov は対象の markdown ファイルを指定する際

$ drakov -f "src/**/*.md"

というように正規表現で指定することができるので、ファイルが複数に分割されていても問題ない。
" でくくらないと期待通りに動かないので注意(シェル環境が zsh だったからかも)

また、--watch オプションをつけておくと markdown ファイルの変更を検知して自動的にリロードしてくれる。

(コマンド例)

$ drakov -f "src/**/*.md" -p 8081 --watch


TODO

結局いまだに dredd というツールを調べられていない。