Swaggerの概要をまとめてみた。【Swagger Codegen編】

# 概要
前回に引き続きSwagger Codegenを使ってみました。Swaggerの他のツールについてざっと把握したい方は、[Swaggerの概要をまとめてみた](http://qiita.com/gcyata/items/342073fa7607fd4082bd)をご覧ください。

この記事で扱うのは表の一番下、Swagger Codegen です。

|ツール|説明|
|:-------------|:-----------------|
|[Swagger Spec](https://swagger.io/specification/)|REST APIに対して Swagger の仕様に準じたドキュメント|
|[Swagger Editer](https://swagger.io/swagger-editor/)|Swagger Spec の設計書を記載するためのエディタ|
|[Swagger UI](https://swagger.io/swagger-ui/)|Swagger Spec で記載された設計からドキュメントをHTML形式で自動生成するツール|
|[Swagger Codegen](https://swagger.io/swagger-codegen/)|Swagger Spec で記載された設計からAPIのスタブを自動生成|

# Swagger Codegen とは

Swagger Specで記載された設計からクライアント/サーバコードを生成するコマンドラインツールです。数多くの言語やフレームワークに対応しています。

## Swagger Codegen のインストール

先ずはJavaをインストールします。

```
$ brew cask install java
```

続いて、Swagger Codegen をインストールします。

```
$ brew install swagger-codegen
```

以下のコマンドでスタブコードを作成します。`-i`は元になるjsonを`-l`は言語を指定するオプションです。今回はnodejsで進めます。

```
$ swagger-codegen generate -i http://petstore.swagger.io/v2/swagger.json -l nodejs-server
```

## 実行

`yarn start`コマンドでスタブを実行することができます。

```
$ yarn start
yarn start v0.27.5
$ npm install
up to date in 0.889s
$ node index.js
Your server is listening on port 8080 (http://localhost:8080)
Swagger-ui is available on http://localhost:8080/docs

```
http://localhost:8080/docs にアクセスすると、Swagger UI のAPI仕様が生成されていることを確認できます。

それでは試しにPET APIリクエストをテストしてみます。bodyパラメーターのvalueを入力し`Try it out!`をクリックすることでテストできます。（post/putの場合は`Example Value`をクリックするとValueに値が反映されます。）

![screencapture-localhost-8080-docs-1504851631841.png](https://qiita-image-store.s3.amazonaws.com/0/188446/eb3dc11f-7f98-664a-cf92-edcc56e6faad.png)


以下はレスポンス結果です。

Curl

```
curl -X GET --header 'Accept: application/json'　'http://petstore.swagger.io/v2/pet/12'
```

Request URL

```
http://petstore.swagger.io/v2/pet/12
```

Response Body

```
{
  "id": 12,
  "category": {
    "id": 12,
    "name": "dolly"
  },
  "name": "dolly",
  "photoUrls": [
    "https://www.google.co.in/search?q=petdog&source=lnms&tbm=isch&sa=X&ved=0ahUKEwjFsdiA75LWAhXBLY8KHZ-rBAkQ_AUICigB&biw=1366&bih=638#imgrc=qBuDUuhnAxXBOM:"
  ],
  "tags": [
    {
      "id": 12,
      "name": "dolly"
    }
  ],
  "status": "available"
}
```


Response Code

```
200
```

Response Headers

```
{
  "content-type": "application/json"
}
```

ホストを任意のものに変更する場合は、`api/swagger.yaml`の`host`を書き換えます。

```swagger.yaml
---
swagger: "2.0"
info:
  description: "This is a sample server Petstore server.  You can find out more about\
    \ Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).\
    \  For this sample, you can use the api key `special-key` to test the authorization\
    \ filters."
  version: "1.0.0"
  title: "Swagger Petstore"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "apiteam@swagger.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io" # ここを変更
basePath: "/v2"
tags:
```

またブラウザのアドレスバーに直接http://localhost:8080/v2/pet/12 と入力しアクセスすると、JSON形式で値を返します。

```
{
  "photoUrls": [
    "aeiou"
  ],
  "name": "doggie",
  "id": 0,
  "category": {
    "name": "aeiou",
    "id": 6
  },
  "tags": [
    {
      "name": "aeiou",
      "id": 1
    }
  ],
  "status": "available"
}
```

上記のブラウザから直接アクセスした場合のレスポンスは`controllers/PetService.js`内の`getPetById`関数で定義されています。

```PetService.js
exports.getPetById = function(args, res, next) {
  /**
   * Find pet by ID
   * Returns a single pet
   *
   * petId Long ID of pet to return
   * returns Pet
   **/
  var examples = {};
  examples['application/json'] = {
  "photoUrls" : [ "aeiou" ],
  "name" : "doggie",
  "id" : 0,
  "category" : {
    "name" : "aeiou",
    "id" : 6
  },
  "tags" : [ {
    "name" : "aeiou",
    "id" : 1
  } ],
  "status" : "available"
};
  if (Object.keys(examples).length > 0) {
    res.setHeader('Content-Type', 'application/json');
    res.end(JSON.stringify(examples[Object.keys(examples)[0]] || {}, null, 2));
  } else {
    res.end();
  }
}
```
# あとがき
Swagger Codegenについては以上となります。またAWSのAPI Gatewayに設計したSwaggerをインポートし設計通りのAPI Gatewayを構築できるようなので、使いながら共有できることがあれば記事にまとめようと思います。

# 参考

- [Swagger Codegen](https://swagger.io/swagger-codegen/)
- [GitHub](https://github.com/swagger-api/swagger-codegen)
- [Swagger Codegenを使ったコード自動生成のポイント](https://news.mynavi.jp/itsearch/article/devsoft/2541)
- [外部連携APIのモックサーバをSwaggerを利用して作る](http://lab.aratana.jp/entry/2016/11/02/091504#f-00b485dd)