Skip to main content

Implementar la API de reservas a partir de la especificación OpenAPI

Entrégale a Devin una especificación YAML y obtén manejadores de rutas de Express completamente implementados, modelos de Prisma, validación con Zod y pruebas de integración con Supertest, todo alineado con los patrones de tu base de código existente.
AuthorCognition
CategoryDesarrollo de funcionalidades
1

(Opcional) Analiza los patrones de API existentes

Si no estás seguro de cómo está estructurada tu API de Express o en qué patrones basarte, utiliza Ask Devin para investigarlo primero:También puedes usar DeepWiki para explorar APIs de código abierto con patrones similares; por ejemplo, busca ejemplos de Express + Prisma + Zod para ver cómo otros proyectos estructuran sus handlers de rutas y la validación.Puedes iniciar una sesión de Devin directamente desde Ask Devin, y mantendrá todo lo que haya aprendido como contexto.
2

Configura Devin para usar tu especificación OpenAPI

Comienza indicando a Devin dónde está la especificación y qué recurso debe implementar. Devin lee cada ruta, esquema y definición de error en el YAML y luego las compara con tus rutas existentes de Express para hacer coincidir las convenciones automáticamente.Aquí tienes un extracto del tipo de especificación con la que trabaja Devin: una definición estándar de OpenAPI 3.0 para un recurso de reservas:
# 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
Si tu especificación aún no está incluida en el repositorio, pégala directamente en la sesión o adjunta el archivo YAML/JSON al iniciar.
3

Devin se adapta a tus patrones de Express

Lo más efectivo que puedes hacer es hacer referencia a un recurso bien implementado en tu base de código. Devin estudia ese código y replica la estructura de carpetas, las convenciones de nomenclatura, la cadena de middleware y el manejo de errores, de modo que los nuevos endpoints parezcan escritos por el mismo desarrollador.Por ejemplo, Devin lee src/api/v2/users/router.ts y produce un router de reservas equivalente:
// src/api/v2/bookings/router.ts  (generado por 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 también deriva esquemas de Zod directamente a partir de las definiciones de componentes de OpenAPI, de modo que la validación de solicitudes se mantiene sincronizada con la especificación:
// src/api/v2/bookings/schemas.ts  (generado por 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(),
});
Asegúrate de que la configuración del repositorio incluya la configuración de la base de datos de pruebas y todas las variables de entorno necesarias para que Devin pueda ejecutar toda la batería de pruebas en local. Si tu API necesita credenciales (URL de la base de datos, secreto JWT, etc.), añádelas como Secrets antes de iniciar la sesión o proporciónalas durante la sesión a través del chat.
4

Devin entrega un pull request probado (PR)

Devin lee la especificación, estudia tu código existente e implementa cada endpoint para que se ajuste tanto al contrato de OpenAPI como a las convenciones de tu codebase de Express. Así es como se ve un PR típico:
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 ejecuta la batería de pruebas de Supertest antes de abrir el 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

Itera sobre lo que la especificación no cubre

La especificación OpenAPI define el contrato, pero rara vez captura las reglas de negocio, la lógica de autorización o los requisitos de rendimiento. Utiliza prompts de seguimiento para cubrir los vacíos:
6

Revisa el PR con Devin Review

Una vez que Devin abre la pull request (PR), usa Devin Review para revisar la implementación. Devin Review puede detectar problemas como falta de manejo de errores, formatos de respuesta inconsistentes o endpoints que no coinciden con la especificación.Si Devin Review señala problemas, puedes usar Autofix para que Devin corrija automáticamente los problemas detectados — abre una sesión de seguimiento, aplica las correcciones y envía un commit actualizado sin que tengas que describir manualmente cada cambio.