aglioを使ってmarkdownからAPIドキュメントとStubを作成する

Posted by Tatsuyano on Tue, Sep 15, 2015
In
Tags nodejs, js, gulp

仕事で簡単なAPIを実装する必要があったので、簡単にAPIドキュメントを公開したり、ドキュメントからStubを自動で用意する方法を調べてみた。

で、こちらの記事にやりたいことがまんま載っていた(ありがとうございます!)ので、 記事を参考に自分用のテンプレートを用意した。


Blueprint

Blueprintの記述は下記をページを参照。


api-mockの起動をgulpに設定する

以下のように設定し、$ gulp mock

var gulp    = require('gulp'),
    aglio   = require('gulp-aglio'),
    ApiMock = require('api-mock');

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

gulp.task('api-mock', function () {
  var mockServer = new ApiMock({
    blueprintPath: PUBLISHED_DIR + '/index.md',
    options: {
      port: 3000
    }
  });
  mockServer.run();
});

gulp.task('mock', ['api-mock']);


Vagrantで使う場合、ポートを開ける

vagrant上からaglioとapi-mockを使うには、デフォルトだと80883000を開ける必要があるので、Vagrantファイルに以下の設定を加える。

config.vm.network "forwarded_port", guest: 3000, host: 3000
config.vm.network "forwarded_port", guest: 8088, host: 8088
  • APIドキュメントを閲覧  => http://localhost:8088
  • StubでAPIのテストをする => http://localhost:3000/questions


POSTでJSONのテストをする

GETの場合は、ブラウザからそのままAPIをそのまま叩けばいいが、POSTの場合は curl を使う。

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST \
-d '{"name": "hoge" }' \
http://localhost:3000/user

もしくはChromeアプリのAdvanced REST clientなどを使ってテストする。


参考サイト