API BlueprintでAPIドキュメントを生成し表示させてみた

# API Blueprintとは
API Blueprintは、APIドキュメントを記述するためのMarkdown拡張で、
多くのツールが公開されており、自動でhtmlに変換したり、mock-serverを立てたりできます。

# 環境構築
今回は以下の環境で行いました。
・Vagrant 1.8.1
・CentOS release 6.6 (Final)
・Node.jsバージョン: v0.10.45
・nvmバージョン: 0.31.1

# 今回やりたいこと

web上に下記の画面を表示させる

------
![qiita_api最後.PNG](https://qiita-image-store.s3.amazonaws.com/0/75241/3e586755-bc9a-b1c5-e2ca-4dbad5b2fb21.png)


-------


# 環境構築
それでは行っていきます。
参考サイト：http://dackdive.hateblo.jp/entry/2015/08/07/181723

### 私が最終的に入れたNodeモジュール

|    モジュール     |説明 |
|:-----------------------|:--------------------------------------------------------|
|gulp　　　　　　　　| Node.jsをベースとしたビルドツール |
|aglio　|HTML ドキュメント生成ツール　|
|gulp-aglio        | Blueprintで書かれたMarkdownをHTMLに変換してくれる　　　　　　　　　　　|
|browser-sync 　　　　| Webページを再読み込みしなくても変更が反映される(リアルタイムプレビュー) |
|gulp-rename     | ファイルを簡単にリネームすることができる gulp 用のプラグイン |
|rimraf            | ファイル削除 |
|gulp-ejs         | ファイルを複数分割することができる |
|api-mock          | モックサーバーを立ち上げるときに必要 |

### 1. プラグインなどインストール
####1-1. インストール
  　**Node.js** と **npm** と **nvm** が入っていなければインストールする
　・Node.js
　　サーバーサイドJavascript
　・npm
　　Node.jsのライブラリやパッケージを管理することができるツール
　・nvm
　　Node.jsのバージョンを管理してくれるツール。
　　Node.jsのバージョン切り替えが容易にできます！



##### nvmのインストール

```
▼ nvmのインストール
$ git clone git://github.com/creationix/nvm.git ~/.nvm

▼ nvmを有効化する
$ source ~/.nvm/nvm.sh

▼ nvmのバージョン確認
$ nvm --version
```

##### Node.jsとnpmのインストール
```
▼ インストールできるNode.jsのバージョンを表示させる
$ nvm ls-remote

▼ Node.jsのインストール
$ nvm install v0.10.45

▼ Nodeのバージョン確認
$ node --version

▼ npmのバージョン確認
$ npm --version
```

####1-2. npm init
環境を構築させたいディレクトリで`npm init` を実行する。
[npm init参考](http://qiita.com/sinmetal/items/395edf1d195382cfd8bc)
ひたすらEnter連打でいいかと。package.jsonが作成される。
####1-3. 必要なNodeモジュールをインストールする
**WARN**はあんまり気にしなくていいと思いますが、
**ERR**が出た場合はググッて解決して下さい...多分Nodeのバージョンを変更することによって解決できます。

```
$ npm install -g gulp
$ npm install -g aglio
$ npm install gulp --save-dev
$ npm install gulp-aglio --save-dev

▼ リアルタイムプレビューに必要
$ npm install browser-sync --save-dev
$ npm install gulp-rename --save-dev

▼ 複数ファイル分割に必要
$ npm install rimraf --save-dev
$ npm install gulp-ejs --save-dev

▼ モックサーバに必要
$ npm install -g api-mock
```
[--save-dev](http://d.hatena.ne.jp/seinzumtode/20160226/1456450867)とは

### 2. gulpfileの作成
gulpfile.jsをvimなどを使用して作成する。 [参考コード](https://github.com/zaki-yama/aglio-sample)
>
```gulpfile.js
var gulp = require('gulp'),
    aglio = require('gulp-aglio'),
    browserSync = require('browser-sync'),
    rename = require('gulp-rename'),
    rimraf = require('rimraf'),
    ejs = require('gulp-ejs');

>var reload = browserSync.reload;

>var TEMPLATE_FILES = ['apidocs/**/*.md'],
    LAYOUT_FILE = 'apidocs/layout.md',
    PUBLISHED_DIR = 'published';

>gulp.task('combine', function(){
  return gulp.src(LAYOUT_FILE)
    .pipe(ejs({},{ ext: '.md' }))
    .pipe(rename('index.md'))
    .pipe(gulp.dest(PUBLISHED_DIR));
});

>gulp.task('generate-api-docs', ['combine'], function() {
  return gulp.src(PUBLISHED_DIR + '/index.md')
    .pipe(aglio({template: 'default'}))
    .pipe(gulp.dest(PUBLISHED_DIR));
});

>gulp.task('watch', function () {
  gulp.watch(TEMPLATE_FILES, ['generate-api-docs', reload]);
});

>gulp.task('browserSync', function() {
  browserSync({
    logConnections: true,
    logFileChanges: true,
    notify: true,
    port: 8088,
    open: false,
    server: {
      baseDir: PUBLISHED_DIR
    }
  });
});

>gulp.task('clean', function(cb) {
  rimraf(PUBLISHED_DIR, cb);
});

>gulp.task('publish', ['clean', 'generate-api-docs']);
gulp.task('default', ['generate-api-docs', 'watch', 'browserSync']);
gulp.task('default', ['generate-api-docs', 'watch', 'browserSync']);
```

### 3. 複数のmdファイルを1つのファイルにする
gulpfileに書かれている通り、
まず**apidocsディレクトリ**と**publishedディレクトリ**を作成する。
apidocs内に、mdファイルを作成していく。

#### 3-1. mdファイルの作成
apidocs内にsample1.mdとsample2.mdファイルを作成する。
ファイルの中身は、[こちら](http://dev.classmethod.jp/server-side/api-document-with-api-blueprint/)のサイトのコードを入れてみました。
>
```sample1.md
## ユーザのエンドポイント [/v1/users]

>### ユーザ登録 [POST]

>#### 処理概要

>* ユーザ情報を新しく登録する。
* 登録に成功した場合、アクセストークンを返す。

>+ Request (application/json)

>    + Headers

>            Accept: application/json

>    + Attributes
        + email: test@example.com (string, required) - メールアドレス（format: email）
        + password: abc123 (string, required) - パスワード（pattern: ^[0-9A-Za-z]{6,16}$）

>+ Response 201 (application/json)

>    + Attributes
        + accessToken: f58ba22059f5a8aa8f346e0f40987adab326041fac99029c909bef2c6300821a (string, required) - アクセストークン
```

>
```sample2.md
## ユーザ情報取得 [/v1/groups/{groupId}/users{?userId,mailAddress}]

>### ユーザ情報取得API [GET]

>#### 処理概要

>* 指定した会員の情報を返す。
* userIdかmailAddressいずれかは必須。どちらも指定がない場合、BadRequestを返す。
* userIdとmailAddressがどちらも指定されている場合、userIdの情報を利用し、mailAddressは利用しない。

>+ Parameters

>    + groupId: 11440002 (number, required) - ユーザが所属するグループID
    + userId: 300 (number, optional) - ユーザID
    + mailAddress: some@example.com (string, optional) - ユーザのメールアドレス

>+ Response 200 (application/json)

>    + Attributes
        + user (required)
            + name: wada (string, required)            + age: 18 (number, required)
            + type: 0 (enum, required) - ユーザ種別(0:無料ユーザ, 1:有料ユーザ)
                + 0 (number)
                + 1 (number)
            + profile (object, required)
            + registered: `2015-06-11T08:40:51Z` (string, required)
            + favorites (array)
                + `http://dev.classmethod.jp/` (string)
        + messageHistory (array)
            + (object)
                + id: 22345 (number, required)
                + title: 今日の献立 (string, required)
```

その後、
apidocsにlayout.mdを作成する
layout.mdは複数ファイルを1つのファイル(index.md)に結合させる役割。

```layout.md
FORMAT: 1A

<% include sample1.md %>
<% include sample2.md %>
```

#### 3.2 構成
最終的にこんな感じになります。

```
├── apidocs
│   ├── sample1.md
│   ├── sample2.md
│   └── layout.md
├── gulpfile.js
├── package.json
└── published
    ├── index.html
    └── index.md
```

###4. gulpの実行
#### 4.1 ポートを開ける
vagrantで実行する場合はポートを開ける必要がある。
Vagrantfileに以下の2つを追記する。　[参考サイト](http://blog.10rane.com/2015/09/15/to-create-the-api-documentation-and-the-stub-from-markdown-using-aglio/)

```text:Vagrantfile
config.vm.network "forwarded_port", guest: 3000, host: 3000
config.vm.network "forwarded_port", guest: 8088, host: 8088
```

#### 4.2 実行

`gulp`を実行する。
実行後、
gulpfileが処理され、
**publishedディレクトリ**に**index.md**と**index.html**が自動で作成される。

接続を切るときは`ctrl + C`

アクセスする
http://localhost:8088


上記のURLにアクセスしweb上で以下の画面が表示されたら成功！

![qiita_api最後.PNG](https://qiita-image-store.s3.amazonaws.com/0/75241/d1c8733b-0a1c-023b-d429-ae5e045aca6c.png)


今回はここまで。
また、更新します。


# 参考サイト
http://dackdive.hateblo.jp/entry/2015/08/07/181723
http://dev.classmethod.jp/server-side/api-document-with-api-blueprint/
http://blog.10rane.com/2015/09/15/to-create-the-api-documentation-and-the-stub-from-markdown-using-aglio/
http://blog.amedama.jp/entry/2016/03/08/202403

https://speakerdeck.com/shimastripe/api-blueprintsu-xi-hui-at-wantedly