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
2. gulpfileの作成
gulpfile.jsをvimなどを使用して作成する。 参考コード
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ファイルを作成する。
ファイルの中身は、こちらのサイトのコードを入れてみました。
## ユーザのエンドポイント [/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) - アクセストークン
## ユーザ情報取得 [/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)に結合させる役割。
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つを追記する。 参考サイト
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