Skip to main content

OpenAPI仕様からBookings APIを実装する

Devin に YAML 仕様を渡すだけで、既存のコードベースのパターンに沿った実装済みの Express ルートハンドラー、Prisma モデル、Zod バリデーション、Supertest を用いた統合テスト一式を生成できます。
AuthorCognition
Category機能開発
1

（任意）既存の API パターンを確認する

Express API の構成やどのパターンを参考にすればよいか分からない場合は、まず Ask Devin を使って調査してください:DeepWiki を使って、類似パターンを持つオープンソース API を調査することもできます。たとえば、Express + Prisma + Zod のサンプルを検索して、他のプロジェクトがルートハンドラーやバリデーションをどのように構成しているかを確認できます。Ask Devin から直接 Devin セッションを開始でき、そのセッションでは Ask Devin で得られた内容がそのままコンテキストとして引き継がれます。
2

Devin に使用する OpenAPI 仕様書を指定する

まず、仕様がどこにあり、どのリソースを実装すべきかをDevinに伝えます。DevinはYAML内のすべてのパス、スキーマ、エラー定義を読み取り、既存のExpressルートと突き合わせて、自動的に既存の規約に沿うようにします。Devinが扱う仕様の一例を以下に示します。これは、bookingsリソース向けの標準的なOpenAPI 3.0仕様です。
# openapi/bookings-v2.yaml (抜粋)
openapi: "3.0.3"
info:
  title: Bookings API
  version: "2.0.0"
paths:
  /api/v2/bookings:
    get:
      summary: List bookings
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1 }
        - name: startDate
          in: query
          schema: { type: string, format: date }
        - name: endDate
          in: query
          schema: { type: string, format: date }
      responses:
        "200":
          description: Paginated list of bookings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BookingListResponse"
    post:
      summary: Create a booking
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateBookingInput"
      responses:
        "201":
          description: Booking created
        "409":
          description: Time slot conflict
  /api/v2/bookings/{id}/confirm:
    post:
      summary: Confirm a booking
      responses:
        "200":
          description: Booking confirmed
        "422":
          description: Booking already cancelled
components:
  schemas:
    CreateBookingInput:
      type: object
      required: [title, startTime, endTime, roomId]
      properties:
        title:
          type: string
          maxLength: 200
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        roomId:
          type: string
          format: uuid
もしまだ仕様をリポジトリにコミットしていない場合は、セッションに直接貼り付けるか、開始時に YAML/JSON ファイルを添付してください。
3

Devin は既存の Express パターンに対応します

最も効果的なのは、コードベース内のよく実装されたリソースを参照させることです。Devin はそのコードを解析し、フォルダ構成、命名規則、ミドルウェアのチェーン、エラー処理を再現するため、新しいエンドポイントも同じ開発者が実装したかのように見えるようになります。たとえば Devin は src/api/v2/users/router.ts を読み込み、それに対応する bookings 用の router を生成します。
// src/api/v2/bookings/router.ts  (Devin が生成)
import { Router } from "express";
import { authenticate } from "@/middleware/auth";
import { validate } from "@/middleware/validate";
import { BookingsController } from "./controller";
import {
  createBookingSchema,
  updateBookingSchema,
  listBookingsQuerySchema,
} from "./schemas";

const router = Router();
const ctrl = new BookingsController();

router.use(authenticate);

router.get("/", validate({ query: listBookingsQuerySchema }), ctrl.list);
router.post("/", validate({ body: createBookingSchema }), ctrl.create);
router.get("/:id", ctrl.getById);
router.patch("/:id", validate({ body: updateBookingSchema }), ctrl.update);
router.delete("/:id", ctrl.softDelete);
router.post("/:id/confirm", ctrl.confirm);
router.post("/:id/cancel", ctrl.cancel);

export default router;
Devin は OpenAPI のコンポーネント定義から直接 Zod スキーマも生成するため、リクエストの検証は常に仕様と同期した状態に保たれます。
// src/api/v2/bookings/schemas.ts  (Devinが生成)
import { z } from "zod";

export const createBookingSchema = z.object({
  title: z.string().max(200),
  startTime: z.string().datetime(),
  endTime: z.string().datetime(),
  roomId: z.string().uuid(),
  notes: z.string().max(1000).optional(),
});

export const updateBookingSchema = createBookingSchema.partial();

export const listBookingsQuerySchema = z.object({
  page: z.coerce.number().int().positive().default(1),
  limit: z.coerce.number().int().min(1).max(100).default(20),
  startDate: z.string().date().optional(),
  endDate: z.string().date().optional(),
});
リポジトリのセットアップにテスト用データベースの設定と必要な環境変数を含めておき、Devin がローカルでテストスイート全体を実行できるようにしてください。API に認証情報（database URL、JWT secret など）が必要な場合は、セッションを開始する前にそれらをSecretsとして登録するか、セッション中にチャットで渡してください。
4

Devin はテスト済みの PR を作成して提出します

Devin は仕様書を読み、既存コードを解析し、各エンドポイントを OpenAPI 仕様と Express コードベースの慣習の両方に沿うように実装します。典型的な PR は次のようになります。
feat: Implement /api/v2/bookings endpoints from OpenAPI spec

src/api/v2/bookings/
  router.ts              (Express route definitions + middleware)
  controller.ts          (request handling)
  service.ts             (business logic)
  repository.ts          (Prisma queries)
  schemas.ts             (Zod validation from spec)
prisma/migrations/
  20260219_add_bookings/  (migration)
src/__tests__/
  bookings.integration.ts (Supertest tests)
Devin は PR を作成する前に Supertest のテストスイートを実行します。
  /api/v2/bookings
    GET /
      passes returns paginated bookings (42ms)
      passes filters by date range (38ms)
      passes returns 401 without auth (8ms)
    POST /
      passes creates booking with valid data (61ms)
      passes returns 400 for missing required fields (12ms)
      passes returns 409 for overlapping time slot (29ms)
    PATCH /:id
      passes updates booking fields (22ms)
      passes returns 404 for non-existent booking (9ms)
    POST /:id/confirm
      passes transitions status to confirmed (18ms)
      passes returns 422 for already-cancelled booking (11ms)

  16 passing (412ms)
5

仕様でカバーされていない部分を反復的に改善する

The OpenAPI spec defines the contract but rarely captures business rules, authorization logic, or performance requirements. Use follow-up prompts to fill in the gaps:
6

Devin Review を使って PR をレビューする

Devin が PR を作成したら、実装内容をレビューするために Devin Review を使用します。Devin Review は、エラー処理の抜けやレスポンス形式の不整合、仕様と一致していないエンドポイントなどの問題を検出できます。Devin Review が問題を検出した場合は、Autofix を使って Devin に自動的に修正させることができます。Autofix はフォローアップセッションを開き、修正を適用し、各変更点を手動で説明することなく更新されたコミットをプッシュします。