ドキュメント作成機能付きREST API フレームワークを試す

公開用のAPIを開発するにあたって必須の物といえばドキュメントとテスターだ。先日、そういった用途にとても合う、面白いツールを見つけたので紹介したい。Swaggerという。
もともとScala, Java, Javascript, Ruby, PHPと多言語対応しているため、API作成用部分とUI部分が別々に開発されており、APIの仕様公開用JSONで仕様の情報をやり取りするように作られている。
Node.js+Expressで動作させるまでに手間取ったので以下に単純化した準備用の手順をまとめてみた。

任意のディレクトリを作成し、そこで作業を開始する。

npm install express swagger-node-express
mkdir tmp
cd tmp
git clone https://github.com/wordnik/swagger-ui.git
cd swagger-ui
npm install
npm install -g handlebars
./node_modules/.bin/cake dist
cp -a dist ../../public/docs
sed -i 's/http:\/\/petstore.swagger.wordnik.com//'  public/docs/index.html
cd ../../

そして以下の内容でapp.jsを作成する

var express = require("express");
var swagger = require("swagger-node-express");
var param = require("swagger-node-express/Common/node/paramTypes.js");

var app = express();
app.use(express.bodyParser());
app.use(express.static(__dirname + '/public'));

swagger.setAppHandler(app);
swagger.addModels({
  models: {
    User: {
      id: 'User',
      properties: {
        id: { type: 'long' },
        name: { type: 'string' }
      }
    }
  }
});

var idParam = param.path('id', 'ID of user that needs to be fetched', 'string');
idParam.defaultValue = '1';

swagger.addGet({
  spec: {
    description: 'get user',
    path: '/user.{format}/{id}',
    notes: 'Returns a user based on ID',
    summary: 'Find user by ID',
    method: 'GET',
    params: [ idParam ],
    errorResponses: [swagger.errors.invalid('id')],
    nickname: 'getUserById'
  },
  action: function (req,res) {
    if (!req.params.id) { throw swagger.errors.invalid('id'); }
    res.send({ id: parseInt(req.params.id) });
  }
});

swagger.configure("", "0.1");
app.listen(8080);

node appを実行してhttp://localhost:8080/docs/にアクセスすると 一つだけだが、APIのドキュメントが表示され、テストできる状態になっていることが確認できると思う。

POSTの際のボディの形式がJSONのみだったのでURLエンコード形式でリクエストボディを送ろうと思ったらswagger-uiを修正する必要があったり、 responseClassの情報を定義した際に動作がおかしくなったり（リクエストのContent-Typeがapplication/xmlになった。）まだまだ不完全な部分が多いように見える。
だが、頻繁に複数のAPIを開発、整備するという状況ならばこういったプロジェクトは助けになる可能性が高い。

過去別のブログに技術系の話題を書いていたが、継続していくというのはとても大変だと思う。今回このSwaggerについてぜひ紹介したいと思ったので新しく始めてみた。これを機になにかしらの記事を提供できれば、と思っている。