Implementare l'API Bookings a partire dalla specifica OpenAPI

Non vuoi configurare tutto manualmente? Incolla un collegamento a questa pagina in una sessione di Devin e chiedigli di configurare tutto per te.

(Facoltativo) Analizza i pattern API esistenti

Se non sei sicuro di come sia strutturata la tua API Express o a quali pattern fare riferimento, utilizza Ask Devin per analizzarla prima:Puoi anche usare DeepWiki per esplorare API open source con pattern simili — ad esempio, cerca esempi Express + Prisma + Zod per vedere come altri progetti strutturano i loro route handler e la validazione.Puoi avviare una sessione di Devin direttamente da Ask Devin, e manterrà tutto ciò che ha appreso come contesto.

Collega Devin alla tua specifica OpenAPI

Inizia indicando a Devin dove si trova la specifica e quale risorsa implementare. Devin legge ogni path, schema e definizione di errore nel file YAML, quindi confronta automaticamente le tue route Express esistenti per rispettare le convenzioni.Ecco un estratto del tipo di specifica con cui lavora Devin — una definizione OpenAPI 3.0 standard per una risorsa di prenotazioni:

# openapi/bookings-v2.yaml (excerpt)
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

If your spec isn’t checked into the repo yet, paste it directly into the session or attach the YAML/JSON file when starting.

Devin matches your Express patterns

The single most impactful thing you can do is reference a well-implemented resource in your codebase. Devin studies that code and replicates the folder structure, naming conventions, middleware chain, and error handling — so the new endpoints look like they were written by the same developer.For example, Devin reads src/api/v2/users/router.ts and produces a matching bookings router:

// src/api/v2/bookings/router.ts  (generated by 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 also derives Zod schemas directly from the OpenAPI component definitions, so request validation stays in sync with the spec:

// src/api/v2/bookings/schemas.ts  (generato da 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(),
});

Assicurati che la configurazione dell’ambiente includa la configurazione del database di test e tutte le variabili d’ambiente necessarie affinché Devin possa eseguire l’intera suite di test in locale. Se la tua API richiede credenziali (URL del database, segreto JWT, ecc.), aggiungile come Secrets prima di avviare la sessione — oppure forniscile durante la sessione tramite chat.

Devin consegna una PR testata

Devin legge la specifica, analizza il codice esistente e implementa ogni endpoint in modo che rispetti sia il contratto OpenAPI sia le convenzioni della tua codebase Express. Ecco com’è fatta una PR tipica:

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 esegue la suite di test Supertest prima di aprire la PR:

  /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)

Approfondisci ciò che la specifica non copre

La specifica OpenAPI definisce il contratto ma raramente include le regole di business, la logica di autorizzazione o i requisiti di performance. Usa prompt di follow-up per colmare le lacune:

Rivedi la PR con Devin Review

Quando Devin apre la PR, usa Devin Review per rivedere l’implementazione. Devin Review può individuare problemi come mancata gestione degli errori, formati di risposta incoerenti o endpoint che non corrispondono alla specifica.Se Devin Review segnala dei problemi, puoi usare Autofix per fare in modo che Devin li corregga automaticamente: apre una sessione di follow-up, applica le correzioni e invia un commit aggiornato senza che tu debba descrivere manualmente ogni modifica.

Documentation Index