💨

Dockerを活用してOpenAPI(Swagger UI, ReDoc)とPrismでAPIドキュメントとモックサーバーを爆速で作る

2023/05/01に公開

Docker

APIドキュメント、書いていますか？

OpenAPIを使用することで、YAMLファイルまたはJSONファイルにAPIの仕様を記述するだけで、簡単にAPIドキュメントを作成することができます。作成できるAPIドキュメントには、「Swagger UI」と「ReDoc」の2種類があります。

Swagger UIのデモ:
https://petstore.swagger.io/

ReDocのデモ:
https://redocly.github.io/redoc/

さらに、OpenAPIのYAMLファイルまたはJSONファイルを元に、モックサーバーとして活用できる「Prism」があります。Prismを使用することで、Next.jsやPython、PostmanなどからAPIを送信できるようになります。APIスキーマを軸にしてフロントエンドとバックエンドが連携し、効率的な開発を実現するスキーマ駆動開発が可能です。

Dockerを用いて、これらのツールを同時に利用できる環境を構築しました。この記事は、以下の方々を対象としています。

APIドキュメントを作成したい、または作成してみたい方
APIドキュメント（Swagger, ReDoc）とモックサーバー（Prism）を同時に環境構築したい方

リポジトリ

作業リポジトリは下記リポジトリです。

ファイル内容

openapi.yml

APIドキュメントの内容を記載します。
今回はサンプルとして、1つのAPIを定義します。

openapi.yml

openapi: 3.0.0
info:
  title: Simple User API
  description: A simple API to retrieve user information.
  version: 1.0.0

paths:
  /users/{userId}:
    get:
      summary: Retrieve user information by ID
      description: Retrieve user information by providing a unique user ID.
      parameters:
        - name: userId
          in: path
          description: The unique identifier of the user.
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: User information retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                  name:
                    type: string
                  email:
                    type: string
                    format: email
        "404":
          description: User not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

Dockerfile

@stoplight/prism-cli をインストールし、Prismを用いてモックサーバーを起動するように設定します（ポート番号は3030に指定します）。

FROM node:14
WORKDIR /app
RUN npm install -g @stoplight/prism-cli
COPY . .
CMD ["prism", "mock", "/app/openapi.yml", "-h", "0.0.0.0", "-p", "3030"]

docker-compose.yml

Prism、Swagger UI、ReDoc用それぞれのサービスを定義します。ReDocサービスで指定しているredocly/redocイメージはNginxを使用していますが、Swagger UIと同様のボリュームを指定すると、ボリュームマウントが正しく設定されていないため、ファイルが見つからないというエラーが表示されます。そのため、ボリュームを/usr/share/nginx/html/openapi/openapi.ymlと指定することで解決します。

version: "3"
services:
  prism:
    build: .
    ports:
      - "3030:3030"
  swagger-ui:
    image: swaggerapi/swagger-ui
    environment:
      - SWAGGER_JSON=/openapi/openapi.yml
    volumes:
      - ./openapi.yml:/openapi/openapi.yml
    ports:
      - "3031:8080"
  redoc:
    image: redocly/redoc
    environment:
      - SPEC_URL=/openapi/openapi.yml
    volumes:
      - ./openapi.yml:/usr/share/nginx/html/openapi/openapi.yml
    ports:
      - "3032:80"