Docker + Swagger + Stoplight Prismを用いたAPI仕様書作成環境+APIモックサーバーの構築方法 メモ

• Docker、Swagger、Stoplight Prismを使用したAPI仕様書作成＋APIモックサーバーの構築方法についてメモする。

Swaggerとは

• REST APIのドキュメント記載に関するフォーマット仕様とswagger-uiやswagger-editorなどの周辺ツールを指す。

ツール	説明
Swagger Spec	OpenAPI仕様に則ったAPI仕様
Swagger Editer	OpenAPI仕様に則ったAPI仕様を書くためのエディタ
Swagger UI	OpenAPI仕様に則ったAPI仕様からドキュメントを生成するツール
Swagger Codegen	OpenAPI仕様に則ったAPI仕様からコードを生成するツール

Stoplight Prism

• Stoplight社が提供するOSSのモックサーバー。
• Swagger Specを読み込むことで、APIモックサーバーを起動する。

事前準備

• docker, docker-compose のインストール。
  • インストール方法は割愛する。

環境構築

• ディレクトリ構成

  SwaggerTest --- docker-compose.yml
               L_ api_reference.yaml

• docker-compose.yml

  version: "3"
  services:
    swagger-editor:
      image: swaggerapi/swagger-editor
      container_name: "swagger-editor"
      ports:
        - "10081:8080"
    swagger-ui:
      image: swaggerapi/swagger-ui
      container_name: "swagger-ui"
      ports:
        - "10082:8080"
      volumes:
        - ./api_reference.yaml:/usr/share/nginx/html/api_reference.yaml
      environment:
        API_URL: api_reference.yaml
    swagger-api:
      image: stoplight/prism:3
      container_name: "swagger-api"
      ports:
        - "10083:4010"
      command: mock -h 0.0.0.0 /api_reference.yaml
      volumes:
        - ./api_reference.yaml:/api_reference.yaml

• api_reference.yaml(Swagger Spec)

  • Petstore APIのyamlファイル(公式)を利用する。

動作確認

コンテナ起動

• SwaggerTestディレクトリに移動し、以下のコマンドを実行する。

docker-compose up

Swagger Editor

• http://localhost:10081 にアクセスし、以下の画面が表示されることを確認する。

Swagger UI

• http://localhost:10082 にアクセスし、以下の画面が表示されることを確認する。

Stoplight Prism (APIモックサーバー)

• 以下のリクエストを行い、以下のレスポンスが返却されることを確認する。

リクエスト

  GET /pets HTTP/1.1
  Host: localhost:10083

レスポンス(期待値)

  [
      {
          "id": 0,
          "name": "string",
          "tag": "string"
      }
  ]

参考情報

• Swaggerの概要をまとめてみた。
• Swagger OpenAPIでAPI Referenceを書く
• Stoplight Prism docs