# openapi.yaml - OpenAPI 3.1 仕様書の完全な例
openapi: '3.1.0'
info:
  title: User Management API
  version: '1.0.0'
  description: |
    ユーザー管理のためのRESTful API。
 
    ## 概要
    このAPIは、ユーザーの登録・認証・プロフィール管理を提供します。
 
    ## 認証
    Bearer Token（JWT）による認証が必要です。
    `/auth/login` エンドポイントでトークンを取得してください。
 
    ## レート制限
    - 認証済みユーザー: 1000 req/min
    - 未認証: 100 req/min
 
    ## エラーハンドリング
    全てのエラーレスポンスは RFC 7807 Problem Details 形式に従います。
  contact:
    name: API Support
    email: api-support@example.com
    url: https://developer.example.com/support
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://example.com/terms
 
externalDocs:
  description: 詳細なAPI開発者ガイド
  url: https://developer.example.com/guide
 
servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging
  - url: http://localhost:3000/v1
    description: Local Development
 
tags:
  - name: Users
    description: ユーザー管理操作
  - name: Auth
    description: 認証・認可操作
  - name: Admin
    description: 管理者専用操作
 
paths:
  /users:
    get:
      summary: ユーザー一覧の取得
      description: |
        ページネーション付きのユーザー一覧を返します。
        フィルタリングとソートに対応しています。
      operationId: listUsers
      tags: [Users]
      parameters:
        - name: page
          in: query
          description: ページ番号（1始まり）
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: per_page
          in: query
          description: 1ページあたりの件数
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: sort
          in: query
          description: ソートフィールド
          schema:
            type: string
            enum: [name, email, created_at, updated_at]
            default: created_at
        - name: order
          in: query
          description: ソート順
          schema:
            type: string
            enum: [asc, desc]
            default: desc
        - name: search
          in: query
          description: 名前・メールでの検索（部分一致）
          schema:
            type: string
            maxLength: 100
        - name: role
          in: query
          description: ロールでフィルタ
          schema:
            type: string
            enum: [user, admin, moderator]
        - name: status
          in: query
          description: ステータスでフィルタ
          schema:
            type: string
            enum: [active, inactive, suspended]
      responses:
        '200':
          description: ユーザー一覧
          headers:
            X-Total-Count:
              description: 総件数
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: 残りリクエスト数
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
              examples:
                default:
                  summary: 標準レスポンス例
                  value:
                    data:
                      - id: "550e8400-e29b-41d4-a716-446655440000"
                        name: "田中太郎"
                        email: "tanaka@example.com"
                        role: "admin"
                        status: "active"
                        createdAt: "2024-01-15T09:00:00Z"
                    meta:
                      total: 150
                      page: 1
                      per_page: 20
                      total_pages: 8
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
 
    post:
      summary: ユーザーの作成
      description: |
        新しいユーザーを作成します。
        メールアドレスはシステム全体で一意である必要があります。
      operationId: createUser
      tags: [Users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            examples:
              basic:
                summary: 基本的なユーザー作成
                value:
                  name: "山田花子"
                  email: "yamada@example.com"
              withRole:
                summary: ロール指定でユーザー作成
                value:
                  name: "佐藤次郎"
                  email: "sato@example.com"
                  role: "moderator"
                  profile:
                    bio: "エンジニアリングマネージャー"
                    avatarUrl: "https://example.com/avatars/sato.png"
      responses:
        '201':
          description: ユーザー作成成功
          headers:
            Location:
              description: 作成されたリソースのURL
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '409':
          description: メールアドレスが既に使用されている
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/ValidationError'
 
  /users/{userId}:
    get:
      summary: ユーザー詳細の取得
      operationId: getUser
      tags: [Users]
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: ユーザー詳細
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '404':
          $ref: '#/components/responses/NotFound'
 
    put:
      summary: ユーザー情報の更新
      description: ユーザー情報を完全に置換します。
      operationId: updateUser
      tags: [Users]
      parameters:
        - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: メールアドレスが既に使用されている
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/ValidationError'
 
    patch:
      summary: ユーザー情報の部分更新
      description: 指定されたフィールドのみを更新します。
      operationId: patchUser
      tags: [Users]
      parameters:
        - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchUserRequest'
      responses:
        '200':
          description: 部分更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '404':
          $ref: '#/components/responses/NotFound'
 
    delete:
      summary: ユーザーの削除
      description: |
        ユーザーを論理削除します。
        削除後30日以内であれば復元可能です。
      operationId: deleteUser
      tags: [Users]
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '204':
          description: 削除成功
        '404':
          $ref: '#/components/responses/NotFound'
 
  /auth/login:
    post:
      summary: ログイン
      operationId: login
      tags: [Auth]
      security: []  # 認証不要
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  minLength: 8
      responses:
        '200':
          description: ログイン成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  refresh_token:
                    type: string
                  expires_in:
                    type: integer
                    description: アクセストークンの有効期限（秒）
                  token_type:
                    type: string
                    enum: [Bearer]
        '401':
          description: 認証失敗
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
 
  /auth/refresh:
    post:
      summary: トークンリフレッシュ
      operationId: refreshToken
      tags: [Auth]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [refresh_token]
              properties:
                refresh_token:
                  type: string
      responses:
        '200':
          description: トークン更新成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  expires_in:
                    type: integer
 
  /users/{userId}/avatar:
    put:
      summary: アバター画像のアップロード
      operationId: uploadAvatar
      tags: [Users]
      parameters:
        - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: "画像ファイル（JPEG, PNG, WebP）最大5MB"
            encoding:
              file:
                contentType: image/jpeg, image/png, image/webp
      responses:
        '200':
          description: アップロード成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
        '413':
          description: ファイルサイズ超過
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
 
components:
  parameters:
    UserId:
      name: userId
      in: path
      required: true
      description: ユーザーのUUID
      schema:
        type: string
        format: uuid
      example: "550e8400-e29b-41d4-a716-446655440000"
 
  schemas:
    User:
      type: object
      required: [id, name, email, role, status, createdAt]
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: ユーザーの表示名
        email:
          type: string
          format: email
          description: メールアドレス（一意）
        role:
          type: string
          enum: [user, admin, moderator]
          default: user
          description: ユーザーのロール
        status:
          type: string
          enum: [active, inactive, suspended]
          default: active
          description: アカウントのステータス
        profile:
          $ref: '#/components/schemas/UserProfile'
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
 
    UserProfile:
      type: object
      properties:
        bio:
          type: string
          maxLength: 500
          description: 自己紹介文
        avatarUrl:
          type: string
          format: uri
          description: アバター画像のURL
        location:
          type: string
          maxLength: 100
        website:
          type: string
          format: uri
        socialLinks:
          type: object
          properties:
            twitter:
              type: string
            github:
              type: string
            linkedin:
              type: string
 
    CreateUserRequest:
      type: object
      required: [name, email]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email
        role:
          type: string
          enum: [user, admin, moderator]
          default: user
        profile:
          $ref: '#/components/schemas/UserProfile'
 
    UpdateUserRequest:
      type: object
      required: [name, email]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email
        role:
          type: string
          enum: [user, admin, moderator]
        profile:
          $ref: '#/components/schemas/UserProfile'
 
    PatchUserRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email
        role:
          type: string
          enum: [user, admin, moderator]
        status:
          type: string
          enum: [active, inactive, suspended]
        profile:
          $ref: '#/components/schemas/UserProfile'
      minProperties: 1
 
    UserResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/User'
 
    UserListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
        links:
          $ref: '#/components/schemas/PaginationLinks'
 
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          description: 総件数
        page:
          type: integer
          description: 現在のページ番号
        per_page:
          type: integer
          description: 1ページあたりの件数
        total_pages:
          type: integer
          description: 総ページ数
 
    PaginationLinks:
      type: object
      properties:
        self:
          type: string
          format: uri
        first:
          type: string
          format: uri
        last:
          type: string
          format: uri
        prev:
          type: string
          format: uri
          nullable: true
        next:
          type: string
          format: uri
          nullable: true
 
    Error:
      type: object
      required: [type, title, status]
      properties:
        type:
          type: string
          format: uri
          description: エラータイプを識別するURI
        title:
          type: string
          description: エラーの概要
        status:
          type: integer
          description: HTTPステータスコード
        detail:
          type: string
          description: エラーの詳細説明
        instance:
          type: string
          format: uri
          description: エラーが発生した具体的なリソース
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
              code:
                type: string
          description: フィールド単位のバリデーションエラー
 
  responses:
    Unauthorized:
      description: 認証エラー
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: "https://api.example.com/errors/unauthorized"
            title: "Unauthorized"
            status: 401
            detail: "認証トークンが無効または期限切れです"
 
    NotFound:
      description: リソースが見つからない
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: "https://api.example.com/errors/not-found"
            title: "Not Found"
            status: 404
            detail: "指定されたリソースは存在しません"
 
    ValidationError:
      description: バリデーションエラー
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: "https://api.example.com/errors/validation"
            title: "Validation Error"
            status: 422
            detail: "入力データにエラーがあります"
            errors:
              - field: "email"
                message: "有効なメールアドレスを入力してください"
                code: "invalid_format"
 
    TooManyRequests:
      description: レート制限超過
      headers:
        Retry-After:
          description: 再試行までの秒数
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: "https://api.example.com/errors/rate-limit"
            title: "Too Many Requests"
            status: 429
            detail: "レート制限を超えました。60秒後に再試行してください"
 
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWTベースの認証。`/auth/login` でトークンを取得してください。
        トークンは1時間で期限切れとなります。
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: サービス間通信用のAPIキー
 
security:
  - bearerAuth: []

# 1. JSON Schema との完全互換
# OpenAPI 3.1 は JSON Schema Draft 2020-12 と完全互換
components:
  schemas:
    # if/then/else が使える
    Payment:
      type: object
      properties:
        method:
          type: string
          enum: [credit_card, bank_transfer, crypto]
        cardNumber:
          type: string
        bankAccount:
          type: string
      if:
        properties:
          method:
            const: credit_card
      then:
        required: [cardNumber]
      else:
        if:
          properties:
            method:
              const: bank_transfer
        then:
          required: [bankAccount]
 
    # prefixItems (旧 tuple validation)
    Coordinate:
      type: array
      prefixItems:
        - type: number
          description: 緯度
        - type: number
          description: 経度
      minItems: 2
      maxItems: 2
 
    # contentEncoding, contentMediaType
    FileUpload:
      type: object
      properties:
        content:
          type: string
          contentEncoding: base64
          contentMediaType: image/png
 
# 2. Webhooks
webhooks:
  userCreated:
    post:
      summary: ユーザー作成時のWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                event:
                  type: string
                  const: user.created
                data:
                  $ref: '#/components/schemas/User'
                timestamp:
                  type: string
                  format: date-time
      responses:
        '200':
          description: Webhook受信確認
 
  userDeleted:
    post:
      summary: ユーザー削除時のWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                event:
                  type: string
                  const: user.deleted
                data:
                  type: object
                  properties:
                    userId:
                      type: string
                      format: uuid
                timestamp:
                  type: string
                  format: date-time
      responses:
        '200':
          description: Webhook受信確認
 
# 3. パスアイテムの $ref
paths:
  /users:
    $ref: './paths/users.yaml'
  /users/{userId}:
    $ref: './paths/users-by-id.yaml'

# api/openapi.yaml（ルートファイル）
openapi: '3.1.0'
info:
  $ref: './info.yaml'
servers:
  - url: https://api.example.com/v1
    description: Production
paths:
  /users:
    $ref: './paths/users.yaml'
  /users/{userId}:
    $ref: './paths/users-by-id.yaml'
  /auth/login:
    $ref: './paths/auth.yaml#/login'
components:
  schemas:
    User:
      $ref: './schemas/user.yaml#/User'
    Error:
      $ref: './schemas/common.yaml#/Error'

# api/schemas/user.yaml（分割されたスキーマファイル）
User:
  type: object
  required: [id, name, email, createdAt]
  properties:
    id:
      type: string
      format: uuid
    name:
      type: string
      minLength: 1
      maxLength: 100
    email:
      type: string
      format: email
    role:
      type: string
      enum: [user, admin, moderator]
    createdAt:
      type: string
      format: date-time
 
CreateUserRequest:
  type: object
  required: [name, email]
  properties:
    name:
      type: string
      minLength: 1
      maxLength: 100
    email:
      type: string
      format: email
 
UserResponse:
  type: object
  properties:
    data:
      $ref: '#/User'

# 分割ファイルの結合（バンドル）
# Redocly CLIを使用
npx @redocly/cli bundle api/openapi.yaml -o dist/openapi.yaml
 
# Swagger CLI を使用
npx swagger-cli bundle api/openapi.yaml -o dist/openapi.yaml -t yaml
 
# バリデーション
npx @redocly/cli lint api/openapi.yaml
npx swagger-cli validate api/openapi.yaml

# openapi-typescript: OpenAPIからTypeScript型を生成
npm install -D openapi-typescript
 
# 型生成の実行
npx openapi-typescript openapi.yaml -o src/api/types.ts
 
# watchモード（仕様変更を自動検知）
npx openapi-typescript openapi.yaml -o src/api/types.ts --watch

// 生成された型の使用例（src/api/types.ts から）
import type { paths, components } from './types';
 
// リクエスト型の取得
type CreateUserBody = paths['/users']['post']['requestBody']['content']['application/json'];
// => { name: string; email: string; role?: 'user' | 'admin' | 'moderator'; }
 
// レスポンス型の取得
type UserListResponse = paths['/users']['get']['responses']['200']['content']['application/json'];
 
// スキーマ型の直接参照
type User = components['schemas']['User'];
type Error = components['schemas']['Error'];
 
// クエリパラメータ型
type ListUsersParams = paths['/users']['get']['parameters']['query'];

// openapi-fetch: 型安全なFetchクライアント
import createClient from 'openapi-fetch';
import type { paths } from './types';
 
const client = createClient<paths>({
  baseUrl: 'https://api.example.com/v1',
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
 
// 完全に型安全なAPIコール
// パス、メソッド、パラメータ、レスポンスすべてが型チェックされる
const { data, error } = await client.GET('/users', {
  params: {
    query: {
      page: 1,
      per_page: 20,
      sort: 'created_at',  // enum から選択
      role: 'admin',       // enum から選択
    },
  },
});
 
if (data) {
  // data は UserListResponse 型として推論される
  data.data.forEach(user => {
    console.log(user.name);   // string
    console.log(user.email);  // string
    console.log(user.role);   // 'user' | 'admin' | 'moderator'
  });
}
 
// ユーザー作成（リクエストボディも型チェック）
const { data: newUser, error: createError } = await client.POST('/users', {
  body: {
    name: '田中太郎',
    email: 'tanaka@example.com',
    // role: 'invalid' // ← コンパイルエラー！
  },
});
 
// パスパラメータも型安全
const { data: user } = await client.GET('/users/{userId}', {
  params: {
    path: { userId: '550e8400-e29b-41d4-a716-446655440000' },
  },
});

// orval.config.ts
import { defineConfig } from 'orval';
 
export default defineConfig({
  userApi: {
    input: {
      target: './openapi.yaml',
      validation: true,
    },
    output: {
      target: './src/api/generated.ts',
      client: 'react-query',  // TanStack Query のフック生成
      mode: 'tags-split',     // タグごとにファイル分割
      schemas: './src/api/models',
      mock: true,             // MSW用モックも同時生成
      override: {
        mutator: {
          path: './src/api/custom-fetch.ts',
          name: 'customFetch',
        },
        query: {
          useQuery: true,
          useMutation: true,
          signal: true,
        },
        // Zodバリデーションスキーマも生成
        zod: {
          strict: {
            response: true,
            body: true,
          },
        },
      },
    },
    hooks: {
      afterAllFilesWrite: 'prettier --write',
    },
  },
});

# orval の実行
npx orval
 
# watch モード
npx orval --watch

// 生成されたReact Queryフックの使用例
import { useListUsers, useCreateUser, useGetUser } from './api/generated';
 
function UserList() {
  // 自動生成されたフック（キャッシュキー、型すべて自動）
  const { data, isLoading, error } = useListUsers({
    page: 1,
    per_page: 20,
    role: 'admin',
  });
 
  const createUser = useCreateUser();
 
  const handleCreate = async () => {
    await createUser.mutateAsync({
      data: {
        name: '新規ユーザー',
        email: 'new@example.com',
      },
    });
  };
 
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
 
  return (
    <div>
      {data?.data?.map(user => (
        <UserCard key={user.id} user={user} />
      ))}
      <button onClick={handleCreate}>追加</button>
    </div>
  );
}
 
function UserDetail({ userId }: { userId: string }) {
  // パスパラメータも型安全
  const { data } = useGetUser(userId);
 
  return <div>{data?.data?.name}</div>;
}

# Go サーバースタブ生成（oapi-codegen）
go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@latest
 
oapi-codegen \
  -generate types,server,spec \
  -package api \
  -o server/api/api.gen.go \
  openapi.yaml

// 生成されたインターフェースの実装（Go）
package api
 
import (
    "net/http"
    "github.com/labstack/echo/v4"
)
 
// 生成されたインターフェース
type ServerInterface interface {
    ListUsers(ctx echo.Context, params ListUsersParams) error
    CreateUser(ctx echo.Context) error
    GetUser(ctx echo.Context, userId string) error
    UpdateUser(ctx echo.Context, userId string) error
    DeleteUser(ctx echo.Context, userId string) error
}
 
// 実装
type UserHandler struct {
    userService UserService
}
 
func (h *UserHandler) ListUsers(ctx echo.Context, params ListUsersParams) error {
    users, total, err := h.userService.List(ctx.Request().Context(), ListOptions{
        Page:    params.Page,
        PerPage: params.PerPage,
        Sort:    params.Sort,
        Order:   params.Order,
        Search:  params.Search,
        Role:    params.Role,
    })
    if err != nil {
        return ctx.JSON(http.StatusInternalServerError, Error{
            Type:   "https://api.example.com/errors/internal",
            Title:  "Internal Server Error",
            Status: 500,
        })
    }
 
    totalPages := (total + *params.PerPage - 1) / *params.PerPage
    return ctx.JSON(http.StatusOK, UserListResponse{
        Data: users,
        Meta: PaginationMeta{
            Total:      total,
            Page:       *params.Page,
            PerPage:    *params.PerPage,
            TotalPages: totalPages,
        },
    })
}
 
func (h *UserHandler) CreateUser(ctx echo.Context) error {
    var req CreateUserRequest
    if err := ctx.Bind(&req); err != nil {
        return ctx.JSON(http.StatusUnprocessableEntity, Error{
            Type:   "https://api.example.com/errors/validation",
            Title:  "Validation Error",
            Status: 422,
            Detail: err.Error(),
        })
    }
 
    user, err := h.userService.Create(ctx.Request().Context(), req)
    if err != nil {
        return handleServiceError(ctx, err)
    }
 
    return ctx.JSON(http.StatusCreated, UserResponse{Data: user})
}

# Python サーバースタブ生成（FastAPI）
pip install openapi-generator-cli
 
openapi-generator-cli generate \
  -i openapi.yaml \
  -g python-fastapi \
  -o server/ \
  --additional-properties=packageName=user_api

# 生成されたFastAPIサーバーの拡張例
from fastapi import FastAPI, HTTPException, Depends, Query
from pydantic import BaseModel, EmailStr
from typing import Optional
from uuid import UUID
 
# 生成されたモデル
class User(BaseModel):
    id: UUID
    name: str
    email: EmailStr
    role: str = "user"
    status: str = "active"
    created_at: str
    updated_at: Optional[str] = None
 
class CreateUserRequest(BaseModel):
    name: str
    email: EmailStr
    role: Optional[str] = "user"
 
class UserResponse(BaseModel):
    data: User
 
class PaginationMeta(BaseModel):
    total: int
    page: int
    per_page: int
    total_pages: int
 
class UserListResponse(BaseModel):
    data: list[User]
    meta: PaginationMeta
 
# エンドポイント実装
app = FastAPI(title="User Management API", version="1.0.0")
 
@app.get("/v1/users", response_model=UserListResponse)
async def list_users(
    page: int = Query(1, ge=1),
    per_page: int = Query(20, ge=1, le=100),
    sort: Optional[str] = Query("created_at", enum=["name", "email", "created_at"]),
    order: Optional[str] = Query("desc", enum=["asc", "desc"]),
    search: Optional[str] = Query(None, max_length=100),
    role: Optional[str] = Query(None, enum=["user", "admin", "moderator"]),
    user_service: UserService = Depends(get_user_service),
):
    users, total = await user_service.list_users(
        page=page, per_page=per_page, sort=sort,
        order=order, search=search, role=role,
    )
    return UserListResponse(
        data=users,
        meta=PaginationMeta(
            total=total,
            page=page,
            per_page=per_page,
            total_pages=(total + per_page - 1) // per_page,
        ),
    )
 
@app.post("/v1/users", response_model=UserResponse, status_code=201)
async def create_user(
    body: CreateUserRequest,
    user_service: UserService = Depends(get_user_service),
):
    user = await user_service.create_user(body)
    return UserResponse(data=user)

# .github/workflows/api-codegen.yml
name: API Code Generation
 
on:
  push:
    paths:
      - 'api/openapi.yaml'
      - 'api/**/*.yaml'
  pull_request:
    paths:
      - 'api/openapi.yaml'
      - 'api/**/*.yaml'
 
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Validate OpenAPI Spec
        run: |
          npx @redocly/cli lint api/openapi.yaml
 
      - name: Check for breaking changes
        run: |
          npx @opticdev/optic diff api/openapi.yaml \
            --base origin/main \
            --check
        if: github.event_name == 'pull_request'
 
  generate:
    needs: validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
 
      - name: Generate TypeScript types
        run: |
          npx openapi-typescript api/openapi.yaml \
            -o frontend/src/api/types.ts
 
      - name: Generate API client
        run: |
          cd frontend && npx orval
 
      - name: Generate Go server stubs
        run: |
          go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@latest
          oapi-codegen -generate types,server \
            -package api \
            -o backend/api/api.gen.go \
            api/openapi.yaml
 
      - name: Commit generated code
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -A
          git diff --staged --quiet || \
            git commit -m "chore: regenerate API code from OpenAPI spec"
          git push

# Prismのインストールと起動
npm install -D @stoplight/prism-cli
 
# モックサーバー起動（OpenAPI仕様からレスポンスを自動生成）
npx prism mock openapi.yaml
# → http://localhost:4010 でモックAPIが起動
 
# 動的モック（リクエストに基づいてレスポンスを変化）
npx prism mock openapi.yaml --dynamic
 
# バリデーションプロキシモード
# 実際のAPIに対するリクエスト/レスポンスが仕様に準拠しているか検証
npx prism proxy openapi.yaml https://api.example.com/v1

# Prism モックサーバーへのリクエスト例
# ユーザー一覧取得
curl http://localhost:4010/users?page=1&per_page=10
 
# ユーザー作成
curl -X POST http://localhost:4010/users \
  -H "Content-Type: application/json" \
  -d '{"name": "テスト", "email": "test@example.com"}'
 
# バリデーションエラーの確認
curl -X POST http://localhost:4010/users \
  -H "Content-Type: application/json" \
  -d '{"name": ""}'
# → 422 Validation Error が返る
 
# 特定のレスポンス例を指定
curl http://localhost:4010/users \
  -H "Prefer: example=empty_list"

// msw/handlers.ts - フロントエンド開発用のモックハンドラ
import { http, HttpResponse, delay } from 'msw';
 
// OpenAPI仕様に基づいたモックデータ
const mockUsers = [
  {
    id: '550e8400-e29b-41d4-a716-446655440000',
    name: '田中太郎',
    email: 'tanaka@example.com',
    role: 'admin',
    status: 'active',
    createdAt: '2024-01-15T09:00:00Z',
    updatedAt: '2024-06-01T12:00:00Z',
  },
  {
    id: '550e8400-e29b-41d4-a716-446655440001',
    name: '山田花子',
    email: 'yamada@example.com',
    role: 'user',
    status: 'active',
    createdAt: '2024-02-20T10:30:00Z',
    updatedAt: '2024-05-15T08:00:00Z',
  },
  {
    id: '550e8400-e29b-41d4-a716-446655440002',
    name: '佐藤次郎',
    email: 'sato@example.com',
    role: 'moderator',
    status: 'inactive',
    createdAt: '2024-03-10T14:00:00Z',
    updatedAt: null,
  },
];
 
export const handlers = [
  // ユーザー一覧
  http.get('https://api.example.com/v1/users', async ({ request }) => {
    await delay(200); // リアルな遅延をシミュレート
 
    const url = new URL(request.url);
    const page = parseInt(url.searchParams.get('page') || '1');
    const perPage = parseInt(url.searchParams.get('per_page') || '20');
    const search = url.searchParams.get('search');
    const role = url.searchParams.get('role');
 
    let filtered = [...mockUsers];
 
    // フィルタリング
    if (search) {
      filtered = filtered.filter(u =>
        u.name.includes(search) || u.email.includes(search)
      );
    }
    if (role) {
      filtered = filtered.filter(u => u.role === role);
    }
 
    // ページネーション
    const total = filtered.length;
    const start = (page - 1) * perPage;
    const paged = filtered.slice(start, start + perPage);
 
    return HttpResponse.json({
      data: paged,
      meta: {
        total,
        page,
        per_page: perPage,
        total_pages: Math.ceil(total / perPage),
      },
      links: {
        self: `/users?page=${page}&per_page=${perPage}`,
        first: `/users?page=1&per_page=${perPage}`,
        last: `/users?page=${Math.ceil(total / perPage)}&per_page=${perPage}`,
        prev: page > 1 ? `/users?page=${page - 1}&per_page=${perPage}` : null,
        next: page < Math.ceil(total / perPage)
          ? `/users?page=${page + 1}&per_page=${perPage}`
          : null,
      },
    });
  }),
 
  // ユーザー作成
  http.post('https://api.example.com/v1/users', async ({ request }) => {
    await delay(300);
 
    const body = await request.json() as { name: string; email: string; role?: string };
 
    // バリデーション
    if (!body.name || body.name.length === 0) {
      return HttpResponse.json(
        {
          type: 'https://api.example.com/errors/validation',
          title: 'Validation Error',
          status: 422,
          detail: '入力データにエラーがあります',
          errors: [
            { field: 'name', message: '名前は必須です', code: 'required' },
          ],
        },
        { status: 422 }
      );
    }
 
    // 重複チェック
    if (mockUsers.some(u => u.email === body.email)) {
      return HttpResponse.json(
        {
          type: 'https://api.example.com/errors/conflict',
          title: 'Conflict',
          status: 409,
          detail: 'このメールアドレスは既に使用されています',
        },
        { status: 409 }
      );
    }
 
    const newUser = {
      id: crypto.randomUUID(),
      name: body.name,
      email: body.email,
      role: body.role || 'user',
      status: 'active' as const,
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
    };
 
    mockUsers.push(newUser);
 
    return HttpResponse.json(
      { data: newUser },
      {
        status: 201,
        headers: {
          Location: `/users/${newUser.id}`,
        },
      }
    );
  }),
 
  // ユーザー詳細
  http.get('https://api.example.com/v1/users/:userId', async ({ params }) => {
    await delay(150);
 
    const user = mockUsers.find(u => u.id === params.userId);
    if (!user) {
      return HttpResponse.json(
        {
          type: 'https://api.example.com/errors/not-found',
          title: 'Not Found',
          status: 404,
          detail: '指定されたユーザーは存在しません',
        },
        { status: 404 }
      );
    }
 
    return HttpResponse.json({ data: user });
  }),
 
  // ユーザー削除
  http.delete('https://api.example.com/v1/users/:userId', async ({ params }) => {
    await delay(200);
 
    const index = mockUsers.findIndex(u => u.id === params.userId);
    if (index === -1) {
      return HttpResponse.json(
        {
          type: 'https://api.example.com/errors/not-found',
          title: 'Not Found',
          status: 404,
          detail: '指定されたユーザーは存在しません',
        },
        { status: 404 }
      );
    }
 
    mockUsers.splice(index, 1);
    return new HttpResponse(null, { status: 204 });
  }),
 
  // 認証
  http.post('https://api.example.com/v1/auth/login', async ({ request }) => {
    await delay(500);
 
    const body = await request.json() as { email: string; password: string };
 
    if (body.email === 'admin@example.com' && body.password === 'password123') {
      return HttpResponse.json({
        access_token: 'mock-jwt-token-xxxxx',
        refresh_token: 'mock-refresh-token-xxxxx',
        expires_in: 3600,
        token_type: 'Bearer',
      });
    }
 
    return HttpResponse.json(
      {
        type: 'https://api.example.com/errors/unauthorized',
        title: 'Unauthorized',
        status: 401,
        detail: 'メールアドレスまたはパスワードが正しくありません',
      },
      { status: 401 }
    );
  }),
];

// msw/browser.ts - ブラウザ環境でのセットアップ
import { setupWorker } from 'msw/browser';
import { handlers } from './handlers';
 
export const worker = setupWorker(...handlers);
 
// main.tsx でのセットアップ
async function enableMocking() {
  if (import.meta.env.DEV) {
    const { worker } = await import('./msw/browser');
    return worker.start({
      onUnhandledRequest: 'warn',
    });
  }
}
 
enableMocking().then(() => {
  createRoot(document.getElementById('root')!).render(
    <StrictMode>
      <App />
    </StrictMode>
  );
});

// msw/server.ts - テスト環境でのセットアップ
import { setupServer } from 'msw/node';
import { handlers } from './handlers';
 
export const server = setupServer(...handlers);
 
// vitest.setup.ts
import { beforeAll, afterEach, afterAll } from 'vitest';
import { server } from './msw/server';
 
beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

// wiremock/mappings/get-users.json
{
  "request": {
    "method": "GET",
    "urlPathPattern": "/v1/users",
    "queryParameters": {
      "page": {
        "matches": "[0-9]+"
      }
    }
  },
  "response": {
    "status": 200,
    "headers": {
      "Content-Type": "application/json"
    },
    "jsonBody": {
      "data": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "田中太郎",
          "email": "tanaka@example.com",
          "role": "admin"
        }
      ],
      "meta": {
        "total": 1,
        "page": 1,
        "per_page": 20,
        "total_pages": 1
      }
    }
  }
}

// wiremock/mappings/create-user-validation-error.json
{
  "request": {
    "method": "POST",
    "urlPath": "/v1/users",
    "bodyPatterns": [
      {
        "matchesJsonPath": {
          "expression": "$.name",
          "absent": true
        }
      }
    ]
  },
  "response": {
    "status": 422,
    "headers": {
      "Content-Type": "application/json"
    },
    "jsonBody": {
      "type": "https://api.example.com/errors/validation",
      "title": "Validation Error",
      "status": 422,
      "errors": [
        {
          "field": "name",
          "message": "名前は必須です",
          "code": "required"
        }
      ]
    }
  },
  "priority": 1
}

# WireMock の起動
docker run -d \
  --name wiremock \
  -p 8080:8080 \
  -v $(pwd)/wiremock:/home/wiremock \
  wiremock/wiremock:latest
 
# 動作確認
curl http://localhost:8080/v1/users?page=1

# .spectral.yaml - APIリンティングルール
extends:
  - spectral:oas
 
rules:
  # カスタムルール: オペレーションIDの命名規則
  operation-id-casing:
    given: "$.paths[*][*].operationId"
    then:
      function: casing
      functionOptions:
        type: camel
    severity: error
    message: "operationIdはcamelCaseで記述してください"
 
  # カスタムルール: レスポンスにはdataラッパーを使う
  response-data-wrapper:
    given: "$.paths[*][get,post,put,patch].responses[200,201].content.application/json.schema"
    then:
      field: properties.data
      function: truthy
    severity: warn
    message: "レスポンスはdata プロパティでラップしてください"
 
  # カスタムルール: エラーレスポンスはRFC 7807形式
  error-response-format:
    given: "$.paths[*][*].responses[4XX,5XX].content.application/json.schema"
    then:
      - field: properties.type
        function: truthy
      - field: properties.title
        function: truthy
      - field: properties.status
        function: truthy
    severity: error
    message: "エラーレスポンスはRFC 7807 Problem Details形式にしてください"
 
  # カスタムルール: パスは複数形名詞
  path-plural-resource:
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        match: "^/[a-z]+s(/\\{[^}]+\\}(/[a-z]+s)?)*$"
    severity: warn
    message: "リソースパスは複数形の名詞を使ってください"
 
  # すべてのエンドポイントにタグを付ける
  operation-tag-defined:
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: length
      functionOptions:
        min: 1
    severity: error
    message: "すべてのオペレーションにタグを付けてください"
 
  # 説明文の必須化
  operation-description:
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: description
      function: truthy
    severity: warn
    message: "オペレーションにdescriptionを付けてください"
 
  # セキュリティの定義チェック
  security-defined:
    given: "$"
    then:
      field: security
      function: truthy
    severity: error
    message: "グローバルセキュリティを定義してください"
 
  # プロパティ名のケーシング
  property-casing:
    given: "$.components.schemas[*].properties[*]~"
    then:
      function: casing
      functionOptions:
        type: camel
    severity: error
    message: "プロパティ名はcamelCaseで記述してください"

# Spectralの実行
npx @stoplight/spectral-cli lint openapi.yaml
 
# 出力例:
# openapi.yaml
#  45:17  warning  operation-description   オペレーションにdescriptionを付けてください  paths./users.get
#  78:21  error    operation-id-casing     operationIdはcamelCaseで記述してください     paths./users.post
#
# ✖ 2 problems (1 error, 1 warning, 0 infos, 0 hints)

# api-style-guide.yaml - 組織全体のAPIスタイルガイド
extends:
  - spectral:oas
  - .spectral.yaml  # プロジェクト固有ルール
 
rules:
  # === 命名規則 ===
  # URLはケバブケース
  paths-kebab-case:
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z][a-z0-9-]*(/\\{[a-zA-Z]+\\})?)+$"
    severity: error
 
  # === バージョニング ===
  # URLにバージョンを含める
  path-version:
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "/v[0-9]+"
    severity: error
    message: "サーバーURLにバージョンを含めてください（例: /v1）"
 
  # === ページネーション ===
  # GETリストにはページネーション必須
  pagination-required:
    given: "$.paths[*].get.parameters"
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          contains:
            type: object
            properties:
              name:
                const: page
    severity: warn
    message: "一覧エンドポイントにはpageパラメータを含めてください"
 
  # === セキュリティ ===
  # HTTPSのみ
  https-only:
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "^https://|^http://localhost"
    severity: error
    message: "本番環境ではHTTPSを使用してください"
 
  # === レスポンス ===
  # 成功レスポンスの型定義必須
  response-schema-required:
    given: "$.paths[*][*].responses[2XX].content.application/json"
    then:
      field: schema
      function: truthy
    severity: error

// consumer/tests/user-api.pact.spec.ts
import { PactV4, MatchersV3 } from '@pact-foundation/pact';
import { UserApiClient } from '../src/api/user-client';
 
const { like, eachLike, uuid, iso8601DateTimeWithMillis } = MatchersV3;
 
const provider = new PactV4({
  consumer: 'FrontendApp',
  provider: 'UserService',
  dir: './pacts',
});
 
describe('User API Contract', () => {
  describe('GET /users', () => {
    it('ユーザー一覧を取得できる', async () => {
      await provider
        .addInteraction()
        .given('ユーザーが3人存在する')
        .uponReceiving('ユーザー一覧の取得リクエスト')
        .withRequest('GET', '/v1/users', (builder) => {
          builder.query({ page: '1', per_page: '20' });
          builder.headers({ Authorization: 'Bearer valid-token' });
        })
        .willRespondWith(200, (builder) => {
          builder.headers({ 'Content-Type': 'application/json' });
          builder.jsonBody({
            data: eachLike({
              id: uuid(),
              name: like('田中太郎'),
              email: like('tanaka@example.com'),
              role: like('user'),
              status: like('active'),
              createdAt: iso8601DateTimeWithMillis(),
            }),
            meta: {
              total: like(3),
              page: like(1),
              per_page: like(20),
              total_pages: like(1),
            },
          });
        })
        .executeTest(async (mockServer) => {
          const client = new UserApiClient(mockServer.url);
          const result = await client.listUsers({ page: 1, perPage: 20 });
 
          expect(result.data).toHaveLength(1);
          expect(result.meta.total).toBe(3);
        });
    });
 
    it('ユーザーを作成できる', async () => {
      await provider
        .addInteraction()
        .uponReceiving('ユーザー作成リクエスト')
        .withRequest('POST', '/v1/users', (builder) => {
          builder.headers({
            'Content-Type': 'application/json',
            Authorization: 'Bearer valid-token',
          });
          builder.jsonBody({
            name: '山田花子',
            email: 'yamada@example.com',
          });
        })
        .willRespondWith(201, (builder) => {
          builder.headers({
            'Content-Type': 'application/json',
            Location: like('/users/550e8400-e29b-41d4-a716-446655440000'),
          });
          builder.jsonBody({
            data: {
              id: uuid(),
              name: '山田花子',
              email: 'yamada@example.com',
              role: 'user',
              status: 'active',
              createdAt: iso8601DateTimeWithMillis(),
            },
          });
        })
        .executeTest(async (mockServer) => {
          const client = new UserApiClient(mockServer.url);
          const result = await client.createUser({
            name: '山田花子',
            email: 'yamada@example.com',
          });
 
          expect(result.data.name).toBe('山田花子');
          expect(result.data.email).toBe('yamada@example.com');
        });
    });
  });
});

// provider/tests/user-api.pact-provider.spec.ts
import { Verifier } from '@pact-foundation/pact';
import { app } from '../src/app';
 
describe('Provider Verification', () => {
  let server: any;
 
  beforeAll(async () => {
    server = app.listen(3001);
  });
 
  afterAll(() => server.close());
 
  it('Pact契約を満たしている', async () => {
    const verifier = new Verifier({
      providerBaseUrl: 'http://localhost:3001',
      pactUrls: ['./pacts/FrontendApp-UserService.json'],
      // または Pact Broker から取得
      // pactBrokerUrl: 'https://pact-broker.example.com',
      // providerVersion: process.env.GIT_SHA,
      stateHandlers: {
        'ユーザーが3人存在する': async () => {
          // テストデータのセットアップ
          await seedTestUsers(3);
        },
      },
      requestFilter: (req, res, next) => {
        // テスト用のAuth headerを追加
        req.headers['authorization'] = 'Bearer test-token';
        next();
      },
    });
 
    await verifier.verifyProvider();
  });
});

# Schemathesis: OpenAPI仕様から自動テスト生成
pip install schemathesis
 
# 基本的なテスト実行
schemathesis run http://localhost:3000/v1/openapi.yaml
 
# 詳細オプション
schemathesis run http://localhost:3000/v1/openapi.yaml \
  --checks all \
  --hypothesis-max-examples 100 \
  --auth "Bearer test-token" \
  --base-url http://localhost:3000/v1 \
  --workers 4
 
# 特定のエンドポイントのみテスト
schemathesis run http://localhost:3000/v1/openapi.yaml \
  --endpoint "/users" \
  --method GET
 
# stateful テスト（APIの状態遷移をテスト）
schemathesis run http://localhost:3000/v1/openapi.yaml \
  --stateful=links

# Schemathesis のPythonテストとしての使用
import schemathesis
 
schema = schemathesis.from_url("http://localhost:3000/v1/openapi.yaml")
 
@schema.parametrize()
def test_api(case):
    """OpenAPI仕様に基づいた自動テスト"""
    response = case.call()
    case.validate_response(response)
 
# 特定のエンドポイントのテスト
@schema.parametrize(endpoint="/users", method="POST")
def test_create_user(case):
    response = case.call()
    case.validate_response(response)
 
    if response.status_code == 201:
        data = response.json()
        assert "data" in data
        assert "id" in data["data"]
 
# カスタムチェック
@schema.parametrize()
def test_response_time(case):
    """レスポンスタイムが500ms以内であること"""
    import time
    start = time.time()
    response = case.call()
    elapsed = time.time() - start
 
    assert elapsed < 0.5, f"Response took {elapsed:.2f}s (max: 0.5s)"
    case.validate_response(response)