ローカル環境のSwagger SpecをSwagger UIとSwagger Editorに反映させる手順

バックエンド

Swaggerを利用することでREST APIの仕様を文章化できます。
今回はREST APIの仕様書であるSwagger Specの内容をSwagger UI、Swagger Editorに反映させる方法について紹介します。

下準備: Swagger Specをローカル環境に用意する

Swagger SpecとはREST APIの仕様を文章化したものです。
今回は~/swagger/sample.yamlというファイル名で、以下のようなSwagger Specを用意しました。

swagger: "2.0"
info:
  description: "This is a sample API."
  version: "1.0.0"
  title: "Sample API"
host: "localhost:3000"
basePath: "/api/v1"
tags:
- name: "todo"
  description: "Everything about todos"
schemes:
- "http"
paths:
  /todos/{todoId}:
    get:
      tags:
      - "todo"
      summary: "Find todo by ID"
      description: "Returns a single id"
      operationId: "getTodoById"
      produces:
      - "application/json"
      parameters:
      - name: "todoId"
        in: "path"
        description: "ID of todo to return"
        required: true
        type: "integer"
        format: "int64"
      responses:
        200:
          description: "successful operation"
        404:
          description: "Todo not found"

Swagger Specの情報をSwagger UIに反映させる方法

Swagger UIとはSwagger Specの情報を反映させた静的ページを生成するツールのことを言います。
Swagger UIはSwagger Specの情報を可視化するだけでなく、画面上からREST APIを実行する機能も提供しています。

今回はDockerを利用してSwagger UIの環境を構築します。
swagger-uiのインストール手順1を参考に、以下のコマンドを実行します。

$ cd ~/swagger

$ docker run -p 80:8080 -e SWAGGER_JSON=/sample.yaml -v ~/swagger/sample.yaml:/sample.yaml swaggerapi/swagger-ui

docker runコマンドについて補足説明をします。

-vオプションを利用して、ローカル環境(ホスト)の~/swagger/sample.yamlをコンテナの/sample.yamlにコピーします。
SWAGGER_JSONという環境変数にはSwagger UIに反映させるSwagger Specのファイル名を指定します。
-vオプションによってローカル環境のSwagger Specがコンテナの/sample.yamlに配置されているため、コンテナのSwagger UIにローカルのSwagger Specの内容が反映されます。
-pオプションでホストの80番ポートとコンテナの8080番ポートを紐づけているため、http://localhostにアクセスすると以下のような画面が表示されます。

Swagger Specの情報をSwagger Editorに反映させる方法

Swagger EditorとはSwagger Specを編集するエディタのことを言います。
Swagger Editorを利用することでSwagger Specを修正しながらSwagger UIの変化をリアルタイムで見られます。

Dockerを利用する方法

swagger-editorのインストール手順2を参考に、以下のコマンドを実行します。

$ cd ~/swagger

$ docker run -p 81:8080 -e SWAGGER_FILE=/sample.yaml -v ~/swagger/sample.yaml:/sample.yaml swaggerapi/swagger-editor

今回の例ではホストの81番ポートで紐付けを行っているため、http://localhost:81にアクセスすると以下のような画面が表示されます。

Visual Studio Codeのプラグインを利用する方法

Dockerを利用してSwagger Editorを起動する場合、デフォルトのままではSwagger Editor上で修正したSwagger Specの内容がローカルに同期されません。

Visual Studio Codeを利用している場合はSwagger Viewerというプラグインを利用する方法がオススメです。

Swagger Viewerを利用すると、以下のような感じでSwagger UIを見ながらSwagger SpecをVisual Studio Code上で修正できます。

まとめ

以上でSwagger UIとSwagger Editorの環境構築手順の紹介を終わります。

この記事がいいなと思いましたらTwitter(@nishina555)のフォローもよろしくお願いします!