Skip to main content

Implementar API de reservas a partir da especificação OpenAPI

Entregue ao Devin uma especificação YAML e obtenha handlers de rotas Express totalmente implementados, modelos Prisma, validação com Zod e testes de integração com Supertest — todos alinhados aos padrões existentes da sua base de código.
AuthorCognition
CategoryDesenvolvimento de funcionalidades
1

(Opcional) Analise seus padrões de API existentes

Se você não tiver certeza de como sua API Express está estruturada ou quais padrões deve usar como referência, use o Ask Devin para investigar primeiro:Você também pode usar o DeepWiki para explorar APIs open source com padrões semelhantes — por exemplo, pesquise por exemplos de Express + Prisma + Zod para ver como outros projetos estruturam seus route handlers e validações.Você pode iniciar uma sessão do Devin diretamente a partir do Ask Devin, e essa sessão vai aproveitar tudo o que ele aprendeu como contexto.
2

Conecte o Devin à sua especificação OpenAPI

Comece dizendo ao Devin onde está a especificação e qual recurso implementar. Devin lê todos os paths, schemas e definições de erro no YAML e, em seguida, cruza isso com suas rotas Express existentes para alinhar automaticamente às convenções.Aqui está um trecho do tipo de especificação com a qual o Devin trabalha — uma definição padrão OpenAPI 3.0 para um recurso de reservas:
# openapi/bookings-v2.yaml (trecho)
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 sua especificação ainda não tiver sido adicionada ao repositório, cole-a diretamente na sessão ou anexe o arquivo YAML/JSON ao iniciar.
3

O Devin se adapta aos seus padrões do Express

A ação mais impactante que você pode tomar é referenciar um recurso bem implementado na sua base de código. Devin estuda esse código e replica a estrutura de pastas, convenções de nomenclatura, cadeia de middleware e tratamento de erros — assim, os novos endpoints parecem ter sido escritos pelo mesmo desenvolvedor.Por exemplo, Devin lê src/api/v2/users/router.ts e produz um router de reservas correspondente:
// src/api/v2/bookings/router.ts  (gerado pelo 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 também deriva esquemas Zod diretamente das definições de componentes do OpenAPI, assim a validação das requisições se mantém alinhada à especificação:
// 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(),
});
Certifique-se de que a sua configuração do repositório inclua a configuração do banco de dados de teste e todas as variáveis de ambiente necessárias para que Devin possa executar a suíte de testes completa localmente. Se a sua API precisar de credenciais (URL do banco de dados, chave secreta JWT, etc.), adicione-as como Secrets antes de iniciar a sessão — ou forneça-as durante a sessão via chat.
4

Devin entrega um PR já testado

Devin lê a especificação, estuda seu código existente e implementa cada endpoint de forma a corresponder tanto ao contrato OpenAPI quanto às convenções da sua base de código em Express. Veja como costuma ser um 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 executa a suíte de testes Supertest antes de abrir o 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

Itere sobre o que a especificação não cobre

A especificação OpenAPI define o contrato, mas raramente captura regras de negócio, lógica de autorização ou requisitos de desempenho. Use prompts de acompanhamento para preencher essas lacunas:
6

Revise o PR com o Devin Review

Quando o Devin abrir um PR, use o Devin Review para revisar a implementação. O Devin Review pode detectar problemas como falta de tratamento de erros, formatos de resposta inconsistentes ou endpoints que não seguem a especificação.Se o Devin Review sinalizar problemas, você pode usar o Autofix para que o Devin corrija automaticamente os problemas apontados — ele abre uma sessão de acompanhamento, aplica as correções e envia um commit atualizado sem que você precise descrever cada alteração manualmente.