O que é Desenvolvimento de API Spec-First?

A maioria dos bugs de API não são erros de codificação. São erros de acordo. O frontend esperava userId, o backend enviou user_id, e ninguém percebeu até o QA. O desenvolvimento de API spec-first corrige isso tornando o contrato a primeira coisa que você escreve, não a última coisa que você documenta.

Neste guia, você escreverá uma pequena especificação OpenAPI à mão e, em seguida, usará esse único arquivo para gerar mocks, testes e documentação antes que qualquer código de servidor exista. A mesma abordagem é conhecida por alguns nomes: desenvolvimento guiado por especificação (spec-driven development), design-first ou contract-first. Todos apontam para a mesma ideia. Concorde com a interface primeiro e depois construa-a.

O que é o desenvolvimento de API spec-first

Desenvolvimento de API spec-first significa que você cria um contrato legível por máquina, geralmente um documento OpenAPI, antes de implementar o endpoint. Esse contrato descreve cada caminho, parâmetro, corpo de requisição, formato de resposta e código de status. Uma vez que ele existe, torna-se a fonte da verdade para todos que interagem com a API.

A especificação não é uma documentação que fica atrás do código. Ela lidera. As equipes de frontend constroem a partir de um mock gerado por ela. O QA escreve testes contra ela. O backend implementa para satisfazê-la. Quando todos os três concordam com o mesmo arquivo, a integração deixa de ser um jogo de adivinhação.

Isso inverte a ordem usual. No desenvolvimento code-first, você escreve os manipuladores e depois os descreve, muitas vezes manualmente, muitas vezes desatualizados dentro de um sprint. Em um fluxo de trabalho design-first, a descrição vem primeiro e o código responde a ela. Essa única mudança move a maioria dos problemas de integração para o início do projeto, onde são baratos de corrigir.

Ciclo de vida spec-first vs code-first

As duas abordagens produzem os mesmos endpoints. Elas diferem em quando os problemas surgem e quem pode começar a trabalhar em paralelo.

A coluna da direita é o resultado. Quando o contrato existe primeiro, três equipes param de se bloquear e começam a construir a partir de uma definição compartilhada.

Um exemplo prático de OpenAPI

Vamos projetar um pequeno endpoint /users passo a passo. Vamos construí-lo em partes para que cada parte seja clara e, em seguida, montar o arquivo completo.

Comece com o cabeçalho do documento. Isso declara a versão do OpenAPI e os metadados básicos.

openapi: 3.0.3
info:
 title: Users API
 version: 1.0.0
servers:
 - url: https://api.example.com/v1

Em seguida, defina o esquema User em components. Definí-lo uma vez permite referenciá-lo em todos os lugares, para que o formato permaneça consistente em requisições e respostas.

components:
 schemas:
 User:
 type: object
 required: [id, email, createdAt]
 properties:
 id:
 type: string
 format: uuid
 email:
 type: string
 format: email
 name:
 type: string
 createdAt:
 type: string
 format: date-time

Agora adicione o caminho GET /users. Ele lista usuários e suporta um parâmetro de consulta limit. Observe como a resposta reutiliza o esquema User com $ref em vez de redefini-lo.

paths:
 /users:
 get:
 summary: List users
 operationId: listUsers
 parameters:
 - name: limit
 in: query
 schema:
 type: integer
 default: 20
 maximum: 100
 responses:
 "200":
 description: A list of users
 content:
 application/json:
 schema:
 type: array
 items:
 $ref: "#/components/schemas/User"

Adicione a operação POST /users para criar um usuário. O corpo da requisição define o que o cliente deve enviar, e a resposta 201 retorna o registro criado.

 post:
 summary: Create a user
 operationId: createUser
 requestBody:
 required: true
 content:
 application/json:
 schema:
 type: object
 required: [email]
 properties:
 email:
 type: string
 format: email
 name:
 type: string
 responses:
 "201":
 description: User created
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/User"
 "400":
 description: Invalid request body

Esse é um contrato completo e válido. Ele nomeia cada campo, marca email como obrigatório, limita limit a 100 e declara as respostas de sucesso e erro. Ninguém escreveu uma linha de código de servidor ainda, mas o acordo está travado.

Gerar mocks, testes e documentação a partir da especificação

A razão para escrever a especificação primeiro é a alavancagem. Um arquivo impulsiona três artefatos que as equipes geralmente constroem separadamente.

Mocks. Um servidor mock lê sua especificação e retorna exemplos de respostas que correspondem a cada esquema. As dicas format: uuid e format: email permitem que as ferramentas gerem dados de amostra realistas. Seu frontend chama GET /users e obtém um array de usuários bem formatado no primeiro dia, muito antes do manipulador real existir. Quando a especificação muda, o mock muda com ela.

Testes. Como a especificação declara campos obrigatórios, tipos e códigos de status, ela funciona como um oráculo de teste. Os testes de contrato afirmam que a resposta real para POST /users retorna um 201 com um corpo correspondente ao esquema User, e um 400 quando o email está ausente. Você não está inventando asserções. Você está verificando se a implementação corresponde ao que já foi acordado.

Documentação. A documentação de referência da API é renderizada diretamente a partir da especificação. Cada endpoint, parâmetro e exemplo que você vê na documentação vem do mesmo YAML. Não há uma segunda cópia para manter sincronizada, então a documentação não pode se desviar do contrato.

Isso também é o que faz o spec-first se encaixar bem com um fluxo de trabalho de API git-native: a especificação é um arquivo de texto simples, então cada alteração no contrato aparece como um diff revisável em um pull request. Um revisor pode ver que alguém renomeou email ou removeu um campo obrigatório antes que seja implementado.

Fazendo isso no Apidog

O Apidog suporta isso de ponta a ponta através do Modo Spec-First. Em vez de tratar o arquivo OpenAPI como uma exportação, ele trata o arquivo como o projeto. Você edita o YAML diretamente e o restante do espaço de trabalho segue.

Você escreve ou cola a especificação /users no editor. O Apidog a analisa e imediatamente configura um servidor mock para ambas as operações, para que seu frontend possa começar a chamá-las. A documentação gerada é atualizada conforme você digita. Quando estiver pronto para verificar a implementação, você executa as operações da especificação como casos de teste contra seu backend real e confirma se as respostas correspondem aos esquemas.

A parte que mantém isso honesto é a sincronização bidirecional com o Git. Sua especificação vive em um repositório, e as mudanças fluem em ambas as direções. Edite o YAML em seu editor e faça push, e o Apidog o capturará. Edite no Apidog, e a mudança será registrada como um commit que sua equipe pode revisar. O contrato nunca vive em dois lugares ao mesmo tempo. Se você quiser uma comparação mais profunda de onde isso se encaixa em relação a uma abordagem puramente design-first, consulte spec-first vs design-first no Apidog.

Uma lista de verificação spec-first

Use esta lista antes de considerar uma especificação pronta para ser construída:

• A especificação valida contra o esquema OpenAPI sem erros.
• Cada endpoint declara seu sucesso e pelo menos uma resposta de erro.
• Formas compartilhadas residem em components/schemas e são referenciadas com $ref, não copiadas.
• Os campos obrigatórios são marcados como required, e os formatos (uuid, email, date-time) são definidos onde se aplicam.
• O arquivo de especificação é enviado para controle de versão e revisado em pull requests.
• Um servidor mock é executado a partir da especificação, e o frontend pode acessá-lo.
• Testes de contrato verificam respostas reais contra os esquemas declarados.
• A documentação publicada é renderizada a partir do mesmo arquivo, sem cópia mantida manualmente.

Se todas as caixas estiverem marcadas, suas equipes podem construir em paralelo a partir de um único acordo, em vez de três suposições.

FAQ

Desenvolvimento de API spec-first é o mesmo que design-first?

Na maioria sim. "Design-first" e "contract-first" descrevem o mesmo princípio: escreva a interface antes da implementação. "Spec-first" é o nome mais literal porque o arquivo de especificação OpenAPI é o artefato concreto com o qual você começa. Na prática, os termos são usados de forma intercambiável.

Preciso escrever YAML manualmente?

Não. Você pode criar a especificação em um editor visual e deixar que ele produza o YAML, ou escrever o YAML diretamente se preferir. O ponto não é o formato que você digita, é que o contrato exista e seja acordado antes do código. Muitas equipes misturam ambos, rascunhando visualmente e refinando em YAML durante a revisão.

Como faço para que a especificação e o código não se desalinhem?

Torne a especificação a fonte da verdade e a imponha. Mantenha a especificação no Git para que as alterações sejam revisadas como diffs. Execute testes de contrato na CI para que a build falhe quando uma resposta deixar de corresponder ao esquema. Com a sincronização bidirecional, as edições em qualquer lugar permanecem reconciliadas, o que remove a causa mais comum de desalinhamento.

O desenvolvimento de API spec-first é uma pequena mudança na ordem com uma grande mudança no resultado. Escreva o contrato, concorde com ele e, em seguida, construa-o. Se você quiser experimentar o ciclo completo, abra o Modo Spec-First no Apidog e aponte-o para o seu repositório.