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

13970 ワード
swagger swagger-codegen swagger テキストリンク

概要

前回に引き続きSwagger Codegenを使ってみました。Swaggerの他のツールについてざっと把握したい方は、Swaggerの概要をまとめてみたをご覧ください。

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

ツール 説明
Swagger Spec REST APIに対して Swagger の仕様に準じたドキュメント
Swagger Editer Swagger Spec の設計書を記載するためのエディタ
Swagger UI Swagger Spec で記載された設計からドキュメントをHTML形式で自動生成するツール
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に値が反映されます。）

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

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: "[email protected]"
  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を構築できるようなので、使いながら共有できることがあれば記事にまとめようと思います。

参考