今や RESTful API スキーマ定義のデファクトスタンダードとなった感のある Swagger。ですが、どうにも今いちドキュメントが整備されてないのかわかりづらいのかで、やりたいことがあってもどんなツールがあってどれを選ぶべきか、それらの組み合わせや使い方がわからず困ることが個人的に多いです。

SPA の開発で、swagger.yaml からローカル環境にスタブサーバを立ててフロントエンドのテストに使いたかったのですが、これまたやり方がわからず色々調べてようやくできるようになったので、その備忘録を残しておきます。
なおこの記事は Mac ユーザーの方が対象で、すでに Homebrew と Node.js はインストールされているものとします。

1. スキーマ定義ファイルを用意

まずは Swagger のデモとして超有名な Petstore API の YAML ファイルを落としてきましょう。

mkdir swagger-server
cd swagger-server
wget http://petstore.swagger.io/v2/swagger.yaml

このままだと、Swagger UI から「Try it out」で試したときに petstore.swagger.io を叩きに行ってしまうので、下記のように内容を書き換えておきます。

swagger.yaml

- host: "petstore.swagger.io"
+ host: "localhost:8081"

2. swagger-codegen をインストール

Homebrew でインストールします。すでに Java がインストールしてあるなら、2行目は不要です。

brew update
brew cask install java
brew install swagger-codegen

3. 環境を構築

swagger-codegen generate -i swagger.yaml -l nodejs-server
npm install

今回は nodejs-server を選びましたが、swagger-codegen langs で選択可能な言語・環境リストが表示されるので、別のものがよければそこから選んでください。

4. サーバを起動

node index.js

これで http://localhost:8081/docs/ にアクセスすると、Swagger UI 形式で PetStore のドキュメントが表示されます。
試しに GET /pet/{petId} のエントリポイントがスタブで動いているか確認のため、http://localhost:8081/v2/pet/1 を叩いてみましょう。以下のような JSON データが返ってくるはずです。

GET　/pet/{petId}

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

なお Swagger UI の「Try it out」からでも同様のことができるようになっています。