API BluePrintとSwaggerのドキュメント生成を同時に行う

それそれに利点がある

Web APIのドキュメント記述の言語仕様であるAPI BluePrintとSwaggerですが、 それぞれのドキュメント生成ツールが存在します。

API BluePrint aglio(npm)にて、シンプルなAPIリファレンスを生成可能です。

Swagger Swagger UIにて、リファレンス上で動的にAPIを実行可能な インタラクティブなドキュメントを作成可能です。

両方のドキュメントを作成する手順（一例）

**1.Swagger UIのHTMLをダウンロードしておきます。 (公式ページからも落とせますし、npmにもswagger-uiという名前で存在します)

2. API BluePrintを書く

3. Swaggerに変換する

apib2swaggerという、名前通りAPI BluePrintをswaggerのjsonに変換するコマンドがnpmにあります。

apib2swagger -i someApi.apib -o someApi.json

4. 諸々アップロード後、swagger UIを (swagger jsonを指定して)開く

swagger ui一式 / 生成されたjsonをアップの後、swagger UIのページをhttpで開きます。 この際に、下記のようにswagger jsonのURLを引数で指定することにより、 自身の仕様を読み込んでくれます。

http://(swagger uiの設置場所)/dist/?url=(swagger jsonのURL)

なお、下記のソースを見ると分かるように、引数が無い場合は ハードコーディングされたURLを読み込みます。 （こちらを書き換えてしまうというのもアリ）

[dist/index.html]
———(略)———
  <script type="text/javascript">
    $(function () {
      var url = window.location.search.match(/url=([^&]+)/);
      if (url && url.length > 1) {
        url = decodeURIComponent(url[1]);
      } else {
        url = "http://petstore.swagger.io/v2/swagger.json";
      }
———(略)———

以上です。

BluePrintだけ書けばよいので、自動化してしまえば非常に楽に 軽量(aglio)&インタラクティブドキュメント(swagger UI)が作成可能です!