swagger introduction

tl;dr
------
* swaggerを使うとWebAPIの仕様書を決められたフォーマットに沿って作成できる
* API更新に追従して仕様書の自動更新ができる
* 将来的にはWebAPI仕様書の標準フォーマットになるかも？

メモ
------
* swagger coreとcodegenの役割が少し曖昧になっているから、明確化したい。

swaggerとは
-----------
* swaggerはREST APIのドキュメント記載に関するフォーマット仕様
* RESTful API標準化団体(Open API Initiative）が採用。[OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)として定義されている。
* 実態はJSON(YAML)形式のAPI仕様書とそれを取り巻くツール群
* swaggerプロジェクト自体はフォーマット仕様以外にもドキュメントを書きやすくするツール、ドキュメント自動生成、ウェブベースのドキュメントビューワ等を提供している。

swaggerでのAPI仕様書生成方式
-----------------------------
* トップダウン
 * 仕様を定義（swagger editor）で定義ファイルを生成し、公開（swagger ui）
 * 定義ファイルからソースコードを生成(swagger codegen)
* ボトムアップ
 * 既に存在するREST APIのソースコードから定義を作成する（swagger core）
 * コード内にはSwagger用の[Annotation](https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X)が書いてあること前提（JavaDocのようなものか）
 * 生成された定義を公開（swagger ui）

swaggerの構成要素
----------------
![image](https://qiita-image-store.s3.amazonaws.com/0/64827/14332e7e-3333-5a9e-ac5e-7948b849e5bb.png)

* [Swagger Specification](http://swagger.io/specification/)
 * フォーマット仕様
 * 仕様に沿ってJSON(YAML)形式でAPI定義を記述する。以下サンプル

```yaml
swagger: '2.0'

info:
  version: "1.0.0"
  title: 日本語のテスト

paths:
  /auth:
    get:
      description: |
        test description
        日本語説明文
        
      parameters:
        -
          name: size
          in: query
          description: Size of array
          required: true
          type: number
          format: double
         
      responses:
        200:
          description: Successful responses
          schema:
            title: ArrayOfPersons
            type: array
            items:
              title: Person
              type: object
```

* [Swagger Editor](http://swagger.io/swagger-editor/)
 * Swagger Specificationに沿って記述されたJSON(YAML)ファイルを編集するWebベースのツール。[swaggerの公式ページ](http://editor.swagger.io/)で動作しているものを使うか、ツールをダウンロードしてローカルで動作させる。
 * ツールはNode.js製なのでローカルで使う場合は要Node.js
![image](https://qiita-image-store.s3.amazonaws.com/0/64827/fdc0da06-fe4b-5b18-d073-f166482386fd.png)


* [Swagger UI](http://swagger.io/swagger-ui/)
 * Swagger Specificationに沿って記述されたJSON(YAML)ファイルのビュワー。Webベースのインタフェース。公式ページで[デモ](http://petstore.swagger.io/)が公開されている。
![image](https://qiita-image-store.s3.amazonaws.com/0/64827/768315d8-40be-2cbe-f456-d3d88c4d9aa3.png)

* [Swagger Codegen](http://swagger.io/swagger-codegen/)
 * swaggerの定義ファイル(json)から実際のプログラムコード（サーバ側・クライアント側）を生成するツール。
 * 出力言語は様々（ruby, python, node, php）対応している。

* [Swagger Core](http://swagger.io/swagger-core/)
 * 実際のプログラムコードからswagger定義（json）を生成する。



その他のAPI仕様
-----------------
* [api blueprint](https://apiblueprint.org/)

参考文献
--------
* [RESTful APIの記述標準化を担うSwaggerとは？](https://developer.ntt.com/ja/blog/00f744c3-db45-42c3-86d5-983838ffbeb6)
* [Swagger入門](http://tanakakns.hatenablog.com/entry/2016/02/17/122258)
* [Swagger 入門 - slideshare](http://www.slideshare.net/kakakakakku/swagger-55809002)
* [Swagger / Quick Start Guide](http://www.slideshare.net/gakhov/swagger-quick-start-guide)
* [JAX-RS の REST API ドキュメントを Swagger を使って生成する](http://create-something.hatenadiary.jp/entry/2015/05/07/063000)
* [Scalatra2.2+scalatra-swaggerでREST APIのリファレンスを生成する #1](http://dev.classmethod.jp/server-side/scalatra-swagger01/)