はじめに

API設計を行う際の環境構築についての調べた内容です。

目的

環境構築の目的は以下の2つです。

Swaggerを用いたAPI仕様書の作成(設計)を行う。
作成したAPI仕様書の沿ったレスポンスを返すモックサーバーを作成する。

上の目的を踏まえてSwagger-ui-watcherとAPISproutを用いて環境を作成します。
また、API仕様の作成方法としては専用のツール(Swagger-editor)を用いる方法もありますが、今回はローカルでファイル作成を行う方法を採用します。

Swagger-ui-watcher

Swagger-uiはSwaggerで定義したAPI仕様をブラウザ上で可視化するツールです。
Swagger-ui-watcherはローカルで作成した仕様ファイルの表示に特化したもので、仕様ファイルの変更時にブラウザに表示されたSwagger-uiの画面を自動で更新します。ローカルの仕様ファイルの修正を行う場合はこちらのほうがスムーズな操作が可能です。

APISprout

APISproutはSwaggerを用いて作成されたAPI仕様書を元にレスポンスを返すモックサーバーを自動で構築するツールです。

環境構築

Dockerを用いて環境の構築を行っています。

ディレクトリ構成

.
├── docker-compose.yaml # Composeファイル
│
├── swagger
│   └── swagger.yaml # API仕様ファイル
│
└── swagger-ui-watcher
   └── build
       └── Dockerfile # swagger-ui-watcherのDockerファイル

docker-compose.yaml

version: '3'

services:
  swagger-ui-watcher:
    build: swagger-ui-watcher/build
    image: swagger-ui-watcher
    container_name: swagger-ui-watcher
    ports:
      - 8080:8000
    volumes:
      - ./swagger:/swagger
    command: /swagger/swagger.yaml

  apisprout:
    image: danielgtaylor/apisprout
    container_name: apisprout
    ports:
      - 8000:8000
    volumes:
      - ./swagger/swagger.yaml:/swagger.yaml
    command: /swagger.yaml --watch

Composeファイルではswagger-ui-watcherとapisproutコンテナを定義しています。
Swagger-ui-watcherは公式のイメージ(https://hub.docker.com/r/shotat/swagger-ui-watcher/ )ではなくDockerファイルからイメージを作成しています。
これは仕様ファイル名(swagger.yaml)を外部で設定可能にするためです。

APISproutは公式のイメージ(https://hub.docker.com/r/danielgtaylor/apisprout/ )を元にコンテナの作成を行っています。
コマンドとして仕様ファイル名, watchオプションを指定しています。
watchオプションを設定することでswagger.yamlの自動読み込みが行われます。

Dockerfile(swagger-ui-watcher)

Swagger-ui-watcherコンテナのDockerファイルは以下です。

FROM node:8-alpine

RUN npm install swagger-ui-watcher -g

ENTRYPOINT ["swagger-ui-watcher", "--no-open", "--host", "0.0.0.0"]

VOLUME ["/swagger"]

EXPOSE 8000

swagger.yaml

公式の例にあるswagger.yamlを修正したものを用いて動作確認を行います。
https://swagger.io/docs/specification/basic-structure/

下記ではテスト用サーバーのURLをモックサーバーのURLに変更しています。

openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9
servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://localhost:8000
    description: Optional server description, e.g. Internal staging server for testing
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

動作確認

以下のコマンドでdockerコンテナを起動し、http://localhost:8080 にアクセスします。

docker-compose up -d

以下のような画面が表示されるのでサーバーをプルダウンから選択し、APIをクリックして"Try it out" ⇒ "Execute"を選択することでモックサーバーのAPIを実行することができます。

REST API設計のためのローカル環境構築(Swagger, APISprout)