Swaggerの導入方法と書き方

Swaggerを導入することで、APIのドキュメンテーション作成が簡単になり、またそのドキュメンテーションを元にテストやクライアントコードの生成も行えます。Swaggerの導入と書き方について詳しく説明します。

以下は、SwaggerとそのコンポーネントであるSwagger UIとSwagger Editorをdocker-composeを用いて導入する一例です。

Docker ComposeによるSwaggerの導入

docker-composeを使ってSwagger UIとSwagger Editorをセットアップするには、以下のようにdocker-compose.yamlファイルを作成します。

yamlCopy code
version: "3"
services:
  swagger-ui:
    image: swaggerapi/swagger-ui
    ports:
      - "7070:8080"
    volumes:
      - ./doc/api.yaml:/usr/share/nginx/html/api.yaml
    environment:
      SWAGGER_JSON: /usr/share/nginx/html/api.yaml
      API_URL: /usr/share/nginx/html/api.yaml
  swagger-editor:
    image: swaggerapi/swagger-editor
    ports:
      - "7060:8080"

ここでは、swagger-uiとswagger-editorという2つのサービスを定義しています。それぞれのサービスは、それぞれのポート（7070と7060）でホストに公開されます。また、各サービスはそれぞれのDockerイメージを使用します。そして、プロジェクトのdocker-compose.yamlから見てdoc/api.yamlファイルをSwagger UIのコンテナにマウントします。

OpenAPI Specificationの作成

次にOpenAPI Specificationを記述したapi.yamlファイルを作成します。これがAPIの仕様を定義するドキュメンテーションになります。例えば、以下のように書くことができます。

yamlCopy code
openapi: 3.0.3
info:
  title: Sample API
  description: This is a sample API for demonstration purposes
  version: 1.0.0
servers:
  - url: http://localhost:8080
    description: Local Development Server
paths:
  /users:
    get:
      summary: Returns a list of users
      responses:
        200:
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string
        avatar:
          type: string
          format: uri

このファイルは、Swagger UIやSwagger Editorで読み込まれ、ブラウザ上で閲覧や編集が可能になります。

このようにSwaggerを導入すると、APIの仕様を視覚的に表示し、同時にAPIのテストも行えるようになります。また、ドキュメンテーションは常に最新の状態を保つことができ、開発者間のコミュニケーションを改善します。