Swaggerとswagger-node

##Swaggerとは
SwaggerとはREST APIのドキュメント記載に関するフォーマット仕様と、周辺ツールを指します。現在v2.0。（あと、Swagger v2.0がそのままOpen Api v2.0というのになったらしく、次のv3.0の議論はOpenAPI.nextブランチで行われているようです。）
[OAI/OpenAPI-Specification: The OpenAPI Specification Repository](https://github.com/OAI/OpenAPI-Specification)
[OAI/OpenAPI-Specification at OpenAPI.next](https://github.com/OAI/OpenAPI-Specification/tree/OpenAPI.next)

以下の記事が詳しいです。

[swagger introduction - Qiita](http://qiita.com/tsujimitsu/items/ae886f0e4de86f2b29e4)
[API Meetup Tokyo #15 〜OpenAPI Specification (Swagger) レポート | NTT Communications Developer Portal](https://developer.ntt.com/ja/blog/8f09fd5d-4b0a-470e-acbf-2ce64da63637)

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](https://github.com/swagger-api/swagger-node)
[swagger-nodeのドキュメント](https://github.com/swagger-api/swagger-node/blob/master/docs/README.md)

###インストール

```bash
npm install -g swagger
```

インストールはしばらくかかります。
インストールするとswaggerコマンドが使えるようになります。

以下一通り試してみます。

###1.Swaggerプロジェクトを作る。

swagger関連のモジュールを入れた、webプロジェクトをつくります。

```bash
swagger project create my-project
```

この時、Express、Hapi、Restify、Sailsといったフレームワークの中から使うものを選べます。

作られるプロジェクトは、nodeに選んだフレームワークと、swagger用のミドルウェアを設定したものです。Swagger.yamlファイルを使ってバリデーションやルーティングを行います。

```yaml
# binds a127 app logic to a route
x-swagger-router-controller: hello_world
```

###2.プロジェクトを起動する。

プロジェクトを起動してみます。この状態でソースコードの変更すると再起動してくれます。

```bash
swagger project start my-project
```

プロジェクトに最初から用意されているコードでは`/hello`というアドレスに、パラメータ名`name`で文字列を渡すとjsonを返すapiが定義されているので、
以下の様なcurlを打つと結果が帰ってくるようになっています。

```bash
curl http://127.0.0.1:10010/hello?name=Scott
```

###3.apiのドキュメントをブラウザで見る。

swagger-uiを使って、apiをブラウザで確認してみます。

app.jsを編集して一行追加します。

```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ファイルを編集してみます。以下のコマンドを打ちます。

```bash
swagger project edit my-project
```

そうするとswagger-editorが立ち上がります。ドキュメントを確認しながら編集できます。

Swaggerファイルの編集方法は下記のページが参考になりました。
[swaggerの基礎。swaggerの設定ファイルの書き方とか - Qiita](http://qiita.com/magaya0403/items/0419d84d8df7784ac465)

Tutorial
[Writing OpenAPI (Swagger) Specification Tutorial – Part 1 – Introduction | API Handyman](https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-1-introduction/)

Open APIのサンプルファイル。
[OpenAPI-Specification/examples/v2.0/yaml at master · OAI/OpenAPI-Specification](https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/yaml)



###5.Mockモードで起動する。

Swagger.yamlファイルに書いたapiの仕様に基づいて、適当な値を返すモックサーバーに出来ます。

モックモードでの起動は、./config/default.yamlで設定するか、
swagger project startコマンドにオプションを付けて起動する方法があります。

試すために、Swagger.yamlファイルに新しいapiを書いてみます。
/taskというアドレスにgetするとidと文字列のjsonが返るというapiを書き足しました。

```yaml
...
/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がモックモード指定です。

```bash
swagger project start -m
```

そのあと、http://localhost:10010/docs/ にアクセスして、/taskというapiを叩いてみます。
すると、以下のような結果が帰ってきます。

```json
{
  "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](https://scotch.io/tutorials/speed-up-your-restful-api-development-in-node-js-with-swagger)