Swaggerを使ってインタラクティブなWeb APIドキュメントをつくる

![swagger-top.jpg](https://qiita-image-store.s3.amazonaws.com/0/12939/96fa9078-3a46-a738-77bf-a8b765f7577d.jpeg)

この記事は、微妙に以下の記事の延長線上です。わかりにくければ、こちらから読んでいただいた方がいいかもしれません。

- [LittleBitsを使ったIoTをつくり、家の室温変化のグラフをインターネットから見る（前編） - Qiita](http://qiita.com/weed/items/c6b59a26eab1799d6eb3)

### 「インタラクティブなWeb APIドキュメント」とはどういうものか

[Swagger](http://swagger.io/)というツールを使います。Web APIをYAMLで書いておいて、Swaggerでサーバを立てると、読むだけのドキュメントではなくて、以下のようにパラメータを指定して実際にHTTPリクエストを送ることができるWebページが生成されます。

![Swagger_UI.jpg](https://qiita-image-store.s3.amazonaws.com/0/12939/ce76f18a-c0a0-b8b1-640d-8c4b3a47d6cb.jpeg)

以下が返ってきたレスポンスです。

![Swagger_UI1.jpg](https://qiita-image-store.s3.amazonaws.com/0/12939/81e30625-8b2b-8390-ac99-f069845a4676.jpeg)

以下は実物です。ご自由に動かしてみて下さい。

[インタラクティブなWeb APIドキュメント](https://swagger-cloudbit-p150709.herokuapp.com/docs/)

まだちょっと分かりにくいという方のために、[アノテーションからドキュメントを作れるswaggerの使い方 - gong023の日記](http://gong023.hatenablog.com/entry/2014/05/15/152021)から引用させていただくと、Swaggerの概要は以下のようなものです。

    開発ドキュメントをどうやって書くかという話題は常々ある。そして一番素直なアプローチを取ると、大抵 wiki みたいなアプリケーションを用意して、そこにドキュメント書こうぜという話になる。しかし、この管理は割とすぐ破綻してしまう。 理由はいろいろあるが、最新のコードに追従できなくなるとか、統一されたフォーマットを保証できず書き手によっては何を書いているのか全くわからないとかそういうケースが多い。

    前者について、 swagger はアノテーションでドキュメントを書けるので違いは起きづらくなる。（ それでも不足だが自分でライブラリ作って補った ）

    また後者に関していえば、swagger は API の仕様を記述するためのフォーマットを提供してくれる。

    つまり、swagger は API の記述方法について考える手間を肩代わりし、また違反があれば解析の段階でエラーを吐くのでドキュメントの一貫性保証もしてくれる。

### 作業の流れ

1. **Swagger Editor**を使ってWeb APIドキュメント（swagger.yaml）を書く
2. swagger.yamlからswagger.jsonを生成する
3. Swaggerサーバをダウンロードする
5. Swaggerサーバをローカルで立ててみる
4. Swaggerサーバを修正する
3. SwaggerサーバをHerokuにプッシュして立てる

なお、

- いきなりWeb APIドキュメントを書く方法の他に・・・
- アプリケーション・コードにアノテーションを付けて、それを読み込ませてドキュメントを自動生成させる

こともできますが、今回はやりません（たぶんそうしたほうがコードが読みやすくなって良いと思うのですが、実はやり方がまだよくわからないです）。

### Swagger Editorを使ってWeb APIドキュメントを書く

以下のページがSwagger Editorです。

[Swagger Editor](http://editor.swagger.io/#/)

画面の右側に、出力されるインタラクティブWeb APIドキュメントが表示されます。左側のソースを編集すると、右側のドキュメントがリアルタイムに更新されます。

JSONオブジェクト・モデルの書き方は、以下のページが参考になります。

[rest - How to structure a response with an array that has an href to itself in YAML/swagger.io? - Stack Overflow](http://stackoverflow.com/questions/27626820/how-to-structure-a-response-with-an-array-that-has-an-href-to-itself-in-yaml-swa)

右側のドキュメントから実際にWeb APIを叩くことも可能ですが、そのためにはクロスオリジンを許可しなければなりません（自分でEditorを立てるなど、もっと安全な方法もあります）。

今回のWeb APIサーバはSinatra / Rubyだったので、以下のページを参考にさせて頂きました。

[Sinatraとajax通信でクロスドメイン制約の突破方法 - Qiita](http://qiita.com/chocopuyo/items/ffabccc70eafb0846156)

### swagger.yamlからswagger.jsonを生成する

「File」→「Download JSON」

![Swagger_Editor.jpg](https://qiita-image-store.s3.amazonaws.com/0/12939/d970c5b3-294a-8a39-a63e-df8f6d7e6ec6.jpeg)

### Swaggerサーバをダウンロードする

「Generate Server」→「Node.js」

![Swagger_Editor1.jpg](https://qiita-image-store.s3.amazonaws.com/0/12939/8be60b9b-0679-b2c8-eaaf-0f0dc5eff7a1.jpeg)

### Swaggerサーバをローカルで立ててみる

先ほどダウンロードしたファイルを解凍して、以下のように進めます。

```shell-session
$ cd nodejs-server
$ npm install
```

APIドキュメントは**apiフォルダ**に入ります。**swagger.json**というファイルがあると思います。**Swagger Editor**でAPI ドキュメントを更新したら、jsonファイルを再度ダウンロードして、ここに入れます。

個人的には**Swagger Editor**で「File」→「Download YAML」して、**swagger.yaml**を**apiフォルダ**に保存しておいた方が良いと思います。

```shell-session
$ node index.js
```

これでローカルにSwaggerサーバが起ち上がります。

### Swaggerサーバを修正する

そのままHerokuにプッシュしても動きません。これは困りました。ログを見るとHerokuからポート番号を取得できていないようでしたので、以下のように編集しました。

```js:index.js
--- var serverPort = 8080;
+++ var serverPort = process.env.PORT || 8080;

--- http.createServer(app).listen(8080, function () {
+++ http.createServer(app).listen(process.env.PORT || 8080, function () {
```

また、Herokuにプッシュすると自動で`npm start`が実行されるので、以下のように編集します。

```:package.json
+++  "scripts": {
+++    "start": "node index.js"
+++  }
```

### SwaggerサーバをHerokuにプッシュして立てる

```shell-session
$ git push heroku master
```

お疲れさまでした！

---
ブログやってます：http://weed.nagoya