Swagger Editorで作成したファイルをSwagger UIで見てみる

###Swaggerとは
RESTful APIの記述標準化を目指して「Open API Initiative」 が作成した記述仕様のこと。
ドキュメント周辺が更新されないまま実装とずれていったりするのをしばしば見るので最近ちょくちょく触っている。

###Swaggerで主に使用するツール

1.Swagger Editor
　・Swaggerの仕様にしたがってYAML(JSON)ファイルを編集するツール
2.Swagger UI
　・YAML(JSON)ファイルのビュワー
3.Swagger Core
　・YAML(JSON)からソースコードを作成するツール
4.Swagger Codegen
　・ソースコードからYAML(JSON)ファイルを作成するツール

今回はSwagger Editorで作成したYAML(JSON)ファイルをSwagger UIで見るところまでやる。

###Swaggerのフォーマット

実際に書くにあたってSwaggerのフォーマットに関して学ぶ必要がある

[OpenAPI Specification](http://swagger.io/specification/)に記載されているので参照  

取り敢えずパラメータと型は覚えておく

####パラメータのルール

|     Name    |   Type  |                             Description                              |
|-------------|---------|----------------------------------------------------------------------|
| name        | string  | （必須）　パラメータ                                                 |
| in          | string  | （必須）　パラメータの形式　'query','header','path','body'で記入する |
| description | string  | パラメータの説明                                                     |
| required    | boolean | 必須 or 非必須                                                       |

####型のルール

| Common Name |   Type  |
|-------------|---------|
| integer     | integer |
| long        | integer |
| float       | number  |
| double      | number  |
| string      | string  |
| byte        | string  |
| binary      | string  |
| boolean     | boolean |
| date        | string  |
| dateTime    | string  |
| password    | string  |


### Swagger Editorをインストール

```
git clone https://github.com/swagger-api/swagger-editor.git
cd swagger-editor
npm install
npm start
```

npm startすると自動でエディタの画面が立ち上がる
![swagger1.jpg](https://qiita-image-store.s3.amazonaws.com/0/152039/9baa780e-727a-768d-97e2-aa34f63befa0.jpeg)

また、[オンライン版](http://editor.swagger.io#/)もあるのでそちらを使っても良い。

###記入例

取り敢えず簡単なのを書いてみた。パラメータとかGET・POSTを分けたかったので一貫性はない。

| Method |             Description              |
|--------|--------------------------------------|
| hello  | 良くあるHello World                  |
| name   | フォームから入力された名称を出力する |
| twice  | 入力された数値を2倍にして返却する             |
| date   | 入力された年月日を返却する           |


```
swagger: '2.0'
info:
  version: 1.0.0
  title: Swagger-sample
  description: |
    #### サンプル
schemes:
  - http
host: localhost:8085
basePath: /swagger-sample/sample
paths:
  /hello:
    get:
      responses:
        200:
          description: 最初はHello World
  /name:
    post:
      produces:
        - application/x-www-form-urlencoded
      consumes:
        - application/text/plain
      responses:
        200:
          description: フォームから受け取った名称を出力する
      parameters:
        - name: name
          in: formData
          description: 名称
          type: string
          required: true
  /twice:
    get:
      responses:
        200:
          description: 倍返し
      parameters:
        - name: num
          in: query
          description: 指定する数値
          type: integer
          required: true
  /date/{year}/{month}/{date}:
    get:
      responses:
        200:
          description: 年月日を返却する
      parameters:
        - name: year
          in: path
          description: 年
          type: integer
          required: true
        - name: month
          in: path
          description: 月
          type: integer
          required: true
        - name: date
          in: path
          description: 日
          type: integer
          required: true
```

###Swagger EditorからGenerate Serverをする

Swagger UIから作成したファイルを見るためにGenerate Serverをしてみる。今回はJAX-RSにした。

![swagger4.jpg](https://qiita-image-store.s3.amazonaws.com/0/152039/49f6e677-e26f-86df-77cb-d7a3506e5d72.jpeg)

選択すると`java-client-generated.zip`というファイルがダウンロードできるので任意の場所で展開する。

```
cd java-client-generated
mvn clean package jetty:run
```

Editorで作成したファイルがサーバーにあがっていることを確認する

```
http://localhost:8085/swagger-sample/sample/swagger.json
```

![swagger5.jpg](https://qiita-image-store.s3.amazonaws.com/0/152039/904d80fb-b31f-ce61-cb3b-5740a5a71ba1.jpeg)


###Swagger UIで作成したファイルを見てみる

ここにあるのでダウンロードしてきて任意の場所で展開する

https://github.com/swagger-api/swagger-ui/releases

```
cd swagger-ui-2.2.8
npm install
npm run build
```

ビルドが終わって`./swagger-ui-2.2.8/dist/index.html`をブラウザで見てみるとこんな感じ
![swagger3.jpg](https://qiita-image-store.s3.amazonaws.com/0/152039/c92cf74a-81ac-d738-335e-50b55e60d367.jpeg)

入力欄に`http://localhost:8085/swagger-sample/sample/swagger.json`を入力してみる

見れた
![swagger6.jpg](https://qiita-image-store.s3.amazonaws.com/0/152039/6f1d225d-3e1f-11fe-b075-4be9fffe1c49.jpeg)

###実際触って見た感想

1.Editorの方で構文チェックもしてくれるのでドキュメントのフォーマットの統一を行うのには良い気がする
2.node.jsがあれば動くので導入はそんなに難しくはなかった。
3.OpenAPI Specificationの日本語訳を探したが見つけられなかったので何となく訳したい感じはする。
4.Swagger UIから直接ローカルのファイルを参照しようとするとうまくいかないのが気になる

以上