• 8
    いいね
  • 0
    コメント

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