Swaggerとは
SwaggerとはREST APIのドキュメント記載に関するフォーマット仕様と、周辺ツールを指します。現在v2.0。（あと、Swagger v2.0がそのままOpen Api v2.0というのになったらしく、次のv3.0の議論はOpenAPI.nextブランチで行われているようです。）
OAI/OpenAPI-Specification: The OpenAPI Specification Repository
OAI/OpenAPI-Specification at OpenAPI.next
以下の記事が詳しいです。
swagger introduction - Qiita
API Meetup Tokyo #15 〜OpenAPI Specification (Swagger) レポート | NTT Communications Developer Portal
Swaggerのサイトには、Swagger用のツールが公開されています。
- Swagger Editor
- Swagger UI
- Swagger Codegen
- Swagger Core
Swaggerで書かれたSwagger.yamlから、ドキュメントを生成したり、apiを試せるUIを出したり、テストコードを生成したり、モックサーバーを立てたり、フロントとサーバーのコード生成等々といったことが出来ます。
しかしドキュメントによるとツール群はビルドが必要だったり、ローカルにインストールしたり、一部をWebフレームワーク側に持って行く必要があったり難しそう。
と思ってましたが、npmにあるswagger-nodeを使うと、あらかた入っているのですぐにSwaggerを導入した開発環境を体験できそうです。
Node環境でSwagger
swagger-nodeとは、Swaggerを使った開発ができるようにする環境みたいなかんじです。
swagger用のフレームワークのようなものを入れたプロジェクトの作成や、起動が出来ます。Swagger-toolsも入っています。
swagger-node
swagger-nodeのドキュメント
インストール
npm install -g swagger
インストールはしばらくかかります。
インストールするとswaggerコマンドが使えるようになります。
以下一通り試してみます。
1.Swaggerプロジェクトを作る。
swagger関連のモジュールを入れた、webプロジェクトをつくります。
swagger project create my-project
この時、Express、Hapi、Restify、Sailsといったフレームワークの中から使うものを選べます。
作られるプロジェクトは、nodeに選んだフレームワークと、swagger用のミドルウェアを設定したものです。Swagger.yamlファイルを使ってバリデーションやルーティングを行います。
# binds a127 app logic to a route
x-swagger-router-controller: hello_world
2.プロジェクトを起動する。
プロジェクトを起動してみます。この状態でソースコードの変更すると再起動してくれます。
swagger project start my-project
プロジェクトに最初から用意されているコードでは/helloというアドレスに、パラメータ名nameで文字列を渡すとjsonを返すapiが定義されているので、
以下の様なcurlを打つと結果が帰ってくるようになっています。
curl http://127.0.0.1:10010/hello?name=Scott
3.apiのドキュメントをブラウザで見る。
swagger-uiを使って、apiをブラウザで確認してみます。
app.jsを編集して一行追加します。
swaggerExpress.register(app);
var port = process.env.PORT || 10010;
app.use(swaggerExpress.runner.swaggerTools.swaggerUi()); //追記
app.listen(port);
そして起動して、http://localhost:10010/docs/ にブラウザでアクセスするとswagger-ui画面になっています。
この画面でapiを試すことが出来ます。
画面のdefaultをクリックして、apiの欄をクリックすると、下の方にnameという項目がありその下にTry it outというボタンがあります。
必要があればパラメータを設定したあとにボタンを押すと、レスポンスの結果が表示されます。
4.Swagger.yamlを編集する。
Swagger.yamlファイルを編集してみます。以下のコマンドを打ちます。
swagger project edit my-project
そうするとswagger-editorが立ち上がります。ドキュメントを確認しながら編集できます。
Swaggerファイルの編集方法は下記のページが参考になりました。
swaggerの基礎。swaggerの設定ファイルの書き方とか - Qiita
Tutorial
Writing OpenAPI (Swagger) Specification Tutorial – Part 1 – Introduction | API Handyman
Open APIのサンプルファイル。
OpenAPI-Specification/examples/v2.0/yaml at master · OAI/OpenAPI-Specification
5.Mockモードで起動する。
Swagger.yamlファイルに書いたapiの仕様に基づいて、適当な値を返すモックサーバーに出来ます。
モックモードでの起動は、./config/default.yamlで設定するか、
swagger project startコマンドにオプションを付けて起動する方法があります。
試すために、Swagger.yamlファイルに新しいapiを書いてみます。
/taskというアドレスにgetするとidと文字列のjsonが返るというapiを書き足しました。
...
/task:
x-swagger-router-controller: hello_world
get:
description: task api
operationId: task
responses:
"200":
description: success
schema:
type: "object"
properties:
id:
type: "integer"
format: "int64"
task:
type: "string"
そして以下のコマンドでサーバーを起動します。-mがモックモード指定です。
swagger project start -m
そのあと、http://localhost:10010/docs/ にアクセスして、/taskというapiを叩いてみます。
すると、以下のような結果が帰ってきます。
{
"id": 1,
"task": "Sample text"
}
コントローラの実装を行っていないのに、値が帰ってきました。
さらにモックモードでは細かいカスタマイズが可能です。（api/mocksフォルダのcontrollerを使うようにするなど）
6.testコードのテンプレート
最後に、（ドキュメントに見当たらないけど）テストコードのテンプレートの生成と、実行コマンドがあるようです。
swagger project generate-test
上記でtest/api/clientフォルダにtestコードのテンプレートが生成されます。ここにテストを書いていくと実行コマンドで実行できるのかな？。
swagger project test
とりあえずここまでで、まとめ
swagger.yaml一つでいろいろ済むショートカット感がすごい。モックサーバーだけ使うのもありかもしれない。認証とかになると難しいのかもしれない。既存のプロジェクトをswagger化する仕方とか、Node以外の環境とか、まだいろいろわからない。
以下の様な記事も見かけました。
Speed up your RESTful API development in Node.js with Swagger | Scotch