Claude Code × API開発自動化完全ガイド｜OpenAPI・tRPCスキーマファースト開発・テスト自動生成・CI連携【2026年最新】

## API設計ルール

### 原則
- スキーマファースト: OpenAPI 3.1 YAMLまたはZodスキーマを先に定義し、コードを生成する
- 手書きfetch禁止: openapi-fetchまたはtRPCクライアントを使う
- レスポンス形式: { data: T, error: null } | { data: null, error: { code, message } }
- 認証: Bearer token (Authorization header)
- バージョニング: URLパス /api/v1/
- エラーフォーマット: RFC 7807 Problem Details準拠

### OpenAPIルール
- 仕様ファイル: openapi/openapi.yaml
- 新規エンドポイント追加時は必ずopenapi.yamlを先に更新
- コード生成: openapi-typescript + openapi-fetchを使用
- バリデーション: npx @redocly/cli lint openapi/openapi.yaml

### tRPCルール
- Zodスキーマを先に定義してからルーターを実装
- inputバリデーションは必ずZodスキーマで定義
- Drizzle連携時はdrizzle-zodのcreateInsertSchema/createSelectSchemaを使う
- SuperjsonはhttpBatchLink内のtransformerに指定（v11記法）

### テスト
- OpenAPI: Orval + MSWでモック自動生成
- tRPC: supertest + callerによる直接テスト
- テストカバレッジ: エンドポイント100%

以下の要件からOpenAPI 3.1仕様のYAMLを生成してください:

エンドポイント:
- GET /api/v1/users（一覧取得、cursorページネーション）
- POST /api/v1/users（新規作成）
- GET /api/v1/users/{id}（詳細取得）
- PUT /api/v1/users/{id}（更新）
- DELETE /api/v1/users/{id}（削除）

共通仕様:
- 認証: Bearer token
- エラー: RFC 7807 Problem Details
- レスポンス: { data: T } / { error: { type, title, status, detail } }
- cursorページネーション: ?cursor=xxx&limit=20

出力先: openapi/openapi.yaml
スキーマのcomponents/schemasも含めてください。

openapi: "3.1.0"
info:
  title: User API
  version: "1.0.0"
servers:
  - url: /api/v1

paths:
  /users:
    get:
      operationId: listUsers
      summary: ユーザー一覧取得
      parameters:
        - name: cursor
          in: query
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/User" }
                  nextCursor:
                    type: string
                    nullable: true
      security:
        - BearerAuth: []

components:
  schemas:
    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 }
        createdAt: { type: string, format: date-time }
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

# openapi-typescriptで型定義を生成
npx openapi-typescript openapi/openapi.yaml -o src/api/schema.d.ts

# 生成された型を使ってopenapi-fetchでAPIクライアントを構築
npm install openapi-fetch

import createClient from "openapi-fetch";
import type { paths } from "./schema";

const api = createClient<paths>({ baseUrl: "/api/v1" });

// 完全に型安全（パス・パラメータ・レスポンスすべて型チェック）
const { data, error } = await api.GET("/users/{id}", {
  params: { path: { id: "user-123" } },
});
// data は User | undefined として推論される

// 一覧取得（cursorページネーション）
const { data: users } = await api.GET("/users", {
  params: { query: { cursor: "abc", limit: 20 } },
});

tRPC v11でユーザーCRUDルーターを実装してください。

要件:
- Zodスキーマで入力バリデーション
- Drizzle ORMでDB操作（drizzle-zodのcreateInsertSchemaを使用）
- cursorページネーション
- エラーハンドリング（TRPCError）
- v11記法（createTRPCClient、transformerはlink内）

テーブル定義（db/schema.ts）はすでにあります。

import { z } from "zod";
import { router, publicProcedure } from "../trpc";
import { users } from "@/db/schema";
import { createInsertSchema } from "drizzle-orm/zod";
import { eq, gt, asc } from "drizzle-orm";
import { TRPCError } from "@trpc/server";

// DBスキーマからZodスキーマを自動生成
const createUserInput = createInsertSchema(users).omit({ id: true, createdAt: true });
const updateUserInput = createInsertSchema(users).partial().omit({ id: true, createdAt: true });

export const userRouter = router({
  list: publicProcedure
    .input(z.object({
      cursor: z.string().optional(),
      limit: z.number().min(1).max(100).default(20),
    }))
    .query(async ({ input, ctx }) => {
      const items = await ctx.db
        .select()
        .from(users)
        .where(input.cursor ? gt(users.id, Number(input.cursor)) : undefined)
        .orderBy(asc(users.id))
        .limit(input.limit + 1);

      const hasMore = items.length > input.limit;
      const data = hasMore ? items.slice(0, -1) : items;

      return {
        data,
        nextCursor: hasMore ? String(data.at(-1)?.id) : null,
      };
    }),

  getById: publicProcedure
    .input(z.object({ id: z.number() }))
    .query(async ({ input, ctx }) => {
      const [user] = await ctx.db
        .select()
        .from(users)
        .where(eq(users.id, input.id));
      if (!user) throw new TRPCError({ code: "NOT_FOUND", message: "ユーザーが見つかりません" });
      return user;
    }),

  create: publicProcedure
    .input(createUserInput)
    .mutation(async ({ input, ctx }) => {
      const [user] = await ctx.db.insert(users).values(input).returning();
      return user;
    }),

  update: publicProcedure
    .input(z.object({ id: z.number(), data: updateUserInput }))
    .mutation(async ({ input, ctx }) => {
      const [user] = await ctx.db
        .update(users)
        .set(input.data)
        .where(eq(users.id, input.id))
        .returning();
      if (!user) throw new TRPCError({ code: "NOT_FOUND" });
      return user;
    }),

  delete: publicProcedure
    .input(z.object({ id: z.number() }))
    .mutation(async ({ input, ctx }) => {
      await ctx.db.delete(users).where(eq(users.id, input.id));
      return { success: true };
    }),
});

import { createTRPCClient, httpBatchLink } from "@trpc/client";
import superjson from "superjson";
import type { AppRouter } from "@/server/router";

const trpc = createTRPCClient<AppRouter>({
  links: [
    httpBatchLink({
      url: "/api/trpc",
      transformer: superjson,  // v11: transformerはlink内に指定
    }),
  ],
});

// 完全に型安全（引数・戻り値すべて型推論される）
const user = await trpc.user.create.mutate({
  name: "田中太郎",
  email: "tanaka@example.com",
});
// user は { id: number, name: string, email: string, ... } として推論

petstore:
  input: ./openapi/openapi.yaml
  output:
    target: ./src/api/generated
    client: react-query    # TanStack Queryフック自動生成
    mock: true             # MSWハンドラー自動生成

# コード生成（型・クライアント・MSWモック一括）
npx orval

# 生成されるファイル:
# src/api/generated/
#   ├── users.ts           # TanStack Queryフック
#   ├── users.msw.ts       # MSWハンドラー
#   └── model/             # 型定義

import { setupServer } from "msw/node";
import { getUsersHandler, getUsersByIdHandler } from "@/api/generated/users.msw";
import { render, screen } from "@testing-library/react";
import { UserList } from "./UserList";

// OpenAPIから自動生成されたMSWハンドラーを使用
const server = setupServer(...getUsersHandler(), ...getUsersByIdHandler());

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

test("ユーザー一覧が表示される", async () => {
  render(<UserList />);
  // MSWがOpenAPIスキーマに基づくモックデータを返す
  expect(await screen.findByText(/ユーザー/)).toBeTruthy();
});

import { appRouter } from "@/server/router";
import { createCallerFactory } from "@trpc/server";

const createCaller = createCallerFactory(appRouter);

describe("userRouter", () => {
  it("ユーザーを作成して取得できる", async () => {
    const caller = createCaller({ db: testDb });

    // 作成
    const created = await caller.user.create({
      name: "テストユーザー",
      email: "test@example.com",
    });
    expect(created.id).toBeDefined();

    // 取得
    const user = await caller.user.getById({ id: created.id });
    expect(user.name).toBe("テストユーザー");
  });

  it("存在しないユーザーでNOT_FOUNDエラー", async () => {
    const caller = createCaller({ db: testDb });
    await expect(
      caller.user.getById({ id: 999999 })
    ).rejects.toThrow("NOT_FOUND");
  });
});

name: API Schema Check
on:
  pull_request:
    paths:
      - "openapi/**"

jobs:
  breaking-changes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # OpenAPIバリデーション
      - name: Lint OpenAPI
        run: npx @redocly/cli lint openapi/openapi.yaml

      # Breaking Change検出（oasdiff）
      - uses: oasdiff/oasdiff-action/breaking@v0.0.37
        with:
          base: "main:openapi/openapi.yaml"    # mainブランチの仕様
          revision: "openapi/openapi.yaml"      # PRの仕様
          fail-on: ERR  # breaking changeでCI失敗