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上に下記の画面を表示させる

---

---

環境構築

それでは行っていきます。
参考サイト：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参考
ひたすら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とは

2. gulpfileの作成

gulpfile.jsをvimなどを使用して作成する。 参考コード

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ファイルを作成する。
ファイルの中身は、こちらのサイトのコードを入れてみました。

sample1.md

## ユーザのエンドポイント [/v1/users]

### ユーザ登録 [POST]

#### 処理概要

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

+ Request (application/json)

   + Headers

           Accept: application/json

   + Attributes
        + email: [e-mail] (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: [e-mail] (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つを追記する。　参考サイト

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上で以下の画面が表示されたら成功！

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

参考サイト

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