OpenAPI で API を定義する

OpenAPI 仕様とは

OpenAPI Specification（OAS） は、REST API のインターフェースを機械可読な形式で記述する標準仕様です。 現在の最新バージョンは OpenAPI 3.1 で、JSON Schema との完全互換が実現されています。 仕様ファイルは YAML または JSON で記述し、ここから自動的にドキュメント・クライアント・バリデータを生成できます。

ドキュメント構造

OpenAPI ドキュメントは以下のトップレベルキーで構成されます。

openapi: "3.1.0"
info:
  title: Usaneko API
  version: "1.0.0"
paths:
  /users:
    get:
      summary: ユーザー一覧の取得
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
      required:
        - id
        - name

paths と operations

paths オブジェクトは、各エンドポイントの URL パスと対応する操作を定義します。 各パスの下に HTTP メソッド（get, post, put, delete など）を記述し、パラメータやレスポンスを宣言します。

パラメータには以下の種類があります。

components/schemas による再利用

components/schemas にスキーマを定義し、$ref で参照することで重複を排除できます。 スキーマの継承には allOf を、複数型の選択には oneOf を使います。 共通のエラーレスポンスやページネーション構造もここに定義すると保守性が向上します。

ツール: Swagger UI と Redoc

Swagger UI は OpenAPI ドキュメントをインタラクティブな Web UI として表示するツールです。 ブラウザ上からリクエストを実行でき、開発時の動作確認に最適です。

Redoc は読みやすさに特化した静的ドキュメント生成ツールです。 三カラムレイアウトで仕様とサンプルを同時に表示できるため、外部公開用ドキュメントに向いています。

# Swagger UI を Docker で起動する例
docker run -p 8080:8080 \
  -e SWAGGER_JSON=/api/openapi.yaml \
  -v ./openapi.yaml:/api/openapi.yaml \
  swaggerapi/swagger-ui