Skip to main content

Implementare l'API delle prenotazioni a partire dalla specifica OpenAPI

Passa a Devin una specifica YAML e ottieni handler di route Express completamente implementati, modelli Prisma, validazione Zod e test di integrazione Supertest — in linea con i pattern esistenti della tua codebase.
AuthorCognition
CategorySviluppo funzionalità
1

(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.
2

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
Se la tua specifica non è ancora stata aggiunta al repo, incollala direttamente nella sessione o allega il file YAML/JSON quando inizi.
3

Devin si adatta ai tuoi pattern Express

La cosa più incisiva che puoi fare è fare riferimento a una risorsa ben implementata all’interno della tua codebase. Devin studia quel codice e replica la struttura delle cartelle, le convenzioni di naming, la catena di middleware e la gestione degli errori — così i nuovi endpoint sembrano scritti dallo stesso sviluppatore.Ad esempio, Devin legge src/api/v2/users/router.ts e produce un router delle prenotazioni corrispondente:
// src/api/v2/bookings/router.ts  (generato da 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 genera anche gli schemi Zod direttamente dalle definizioni dei componenti OpenAPI, così la validazione delle richieste rimane allineata con la specifica:
// src/api/v2/bookings/schemas.ts  (generated by 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 del repository includa il database di test e tutte le variabili d’ambiente necessarie, così che Devin possa eseguire l’intera suite di test in locale. Se la tua API richiede credenziali (URL del database, secret JWT, ecc.), aggiungile come Secrets prima di avviare la sessione — oppure forniscele durante la sessione tramite chat.
4

Devin invia una pull request già testata

Devin legge le specifiche, studia il tuo codice esistente e implementa ciascun endpoint in modo che rispetti sia il contratto OpenAPI sia le convenzioni della tua codebase Express. Ecco come si presenta una tipica pull request (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 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)
5

Iterare su quanto non è coperto dalla specifica

The OpenAPI spec 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:
6

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.