O Que Significa Tratar Sua API Spec Como Código?

Seu contrato de API provavelmente está espalhado em três lugares: um diagrama no wiki, uma coleção do Postman exportada meses atrás e um Markdown escrito à mão que já não acompanha o serviço em produção. Quando essas fontes discordam, a equipe passa a adivinhar. E adivinhação quebra integrações.

Experimente o Apidog hoje

Tratar sua especificação de API como código resolve esse problema. Você mantém um arquivo OpenAPI no Git, revisa mudanças via pull request e usa esse contrato para gerar mocks, testes, documentação e SDKs. A especificação deixa de ser um documento auxiliar e passa a ser a fonte de verdade da API.

Este guia mostra como aplicar spec-as-code na prática: onde colocar o arquivo OpenAPI, como revisar mudanças, como conectar geração de artefatos e como evitar desvio entre contrato e implementação.

O que significa spec-as-code

Spec-as-code significa manter a definição da API como um arquivo de texto versionado, normalmente openapi.yaml ou openapi.json.

Não é:

• uma coleção exportada manualmente;
• um documento solto em uma ferramenta;
• uma página de wiki atualizada “quando dá”.

É um arquivo que você pode:

git diff api/openapi.yaml
git blame api/openapi.yaml
git checkout -b change-orders-contract
git revert <commit>

A ideia vem de docs-as-code: documentação vive no mesmo fluxo de trabalho do código. Spec-as-code aplica essa disciplina ao contrato da API. O arquivo OpenAPI é o artefato principal; mocks, testes, documentação e SDKs são derivados dele.

Na prática, isso muda o comportamento da equipe:

• o frontend consulta a especificação para saber o formato de /users/{id};
• o QA valida respostas reais contra a especificação;
• parceiros usam SDKs gerados a partir do mesmo contrato;
• revisores analisam mudanças de API antes do merge.

Um arquivo. Várias saídas. Uma fonte de verdade.

Por que tratar a especificação como código

Quando a especificação entra no Git, ela passa a usar os mesmos mecanismos de controle que você já aplica ao código da aplicação.

1. Revisão por pull request

Uma mudança em um endpoint aparece como diff:

 status:
   type: string
-  enum: [pending, shipped, delivered]
+  enum: [pending, paid, shipped, delivered]

O revisor consegue responder perguntas objetivas:

• algum campo obrigatório foi removido?
• um código de status novo foi adicionado?
• a resposta mudou de forma incompatível?
• o endpoint novo tem operationId?
• os erros estão documentados?

Esse é o centro de um fluxo de trabalho de API nativo do Git.

2. Diffs legíveis

YAML puro é fácil de revisar. Uma mudança pequena aparece como poucas linhas. Isso é muito diferente de comparar exportações manuais ou depender do histórico interno de uma ferramenta hospedada.

Com OpenAPI no Git, você ganha:

• histórico completo;
• autoria por commit;
• revisão assíncrona;
• rollback;
• rastreabilidade de decisões.

3. Versionamento real

Cada mudança de contrato tem commit, autor e timestamp. Você pode:

git tag api-v1.2.0
git checkout -b api-v2-redesign
git revert <bad-contract-change>

Isso torna a evolução da API auditável. Para estratégias de branch, tag e release, veja controle de versão OpenAPI com Git.

4. Fonte única de verdade

Se mocks, testes e documentação derivam do mesmo arquivo, eles não evoluem de forma independente. O fluxo fica simples:

1. altere api/openapi.yaml;
2. revise o PR;
3. valide no CI;
4. gere mocks, docs, testes ou SDKs;
5. publique a mudança.

Comparação prática:

Preocupação	Especificação em ferramenta hospedada	Especificação de API como código
Revisão de mudanças	Manual, fácil de ignorar	Diff de PR, revisão bloqueadora
Histórico	Limitado ou dependente do fornecedor	Log completo do Git
Reversão	Frequentemente manual	git revert
Fonte da verdade	Ambígua	Arquivo commitado
Integração CI	Acoplada à ferramenta	Nativa

OpenAPI como artefato principal

OpenAPI é o formato mais comum para spec-as-code porque é legível por humanos e processável por ferramentas.

Um arquivo mínimo em api/openapi.yaml poderia ser assim:

openapi: 3.1.0

info:
  title: Orders API
  version: 1.2.0

paths:
  /orders/{orderId}:
    get:
      summary: Get an order by ID
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: The requested order
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: Order not found

components:
  schemas:
    Order:
      type: object
      required:
        - id
        - status
        - total
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - shipped
            - delivered
        total:
          type: number
          format: float

Esse arquivo é o contrato.

Se você adicionar um campo em Order, o diff mostra isso. Se mudar o enum de status, o revisor vê imediatamente. Se remover uma propriedade obrigatória, o CI pode bloquear o merge.

Uma estrutura simples de repositório:

my-service/
├── api/
│   └── openapi.yaml
├── src/
├── tests/
└── package.json

Mantenha a especificação perto do serviço que ela descreve. Assim, contrato e implementação evoluem juntos.

O que gerar a partir da especificação

O valor de spec-as-code aparece quando você conecta o arquivo OpenAPI a saídas concretas.

Mocks

Com um servidor mock apontando para openapi.yaml, frontend e mobile podem integrar antes da API estar implementada.

Fluxo prático:

1. defina o endpoint na especificação;
2. gere ou atualize o mock;
3. frontend consome o mock;
4. backend implementa o endpoint real;
5. testes de contrato validam a implementação.

Isso reduz bloqueios entre equipes.

Testes de contrato

Testes de contrato verificam se a API em execução corresponde ao OpenAPI commitado.

Exemplo do que deve falhar:

• endpoint retorna campo não documentado;
• campo obrigatório está ausente;
• status code não foi declarado;
• formato de dado mudou;
• payload de erro diverge da especificação.

O objetivo é detectar drift antes dos clientes.

Documentação

A documentação de referência pode ser renderizada diretamente da especificação. Isso evita manter tabelas de endpoints à mão.

Em vez de escrever manualmente:

GET /orders/{orderId}
Retorna um pedido.

Você documenta no OpenAPI e deixa a documentação ser gerada a partir dele.

SDKs

Clientes tipados podem ser gerados do mesmo contrato. Isso ajuda especialmente quando a API é consumida por múltiplos times, parceiros ou linguagens.

A regra é: mude a entrada, regenere as saídas.

Como o Apidog ajuda no fluxo spec-as-code

Executar spec-as-code manualmente normalmente exige combinar várias peças:

• editor OpenAPI;
• servidor mock;
• gerador de documentação;
• testes de contrato;
• integração com Git;
• scripts de CI.

O Apidog reúne esse fluxo em uma experiência spec-first.

No Modo Spec-First, o arquivo OpenAPI é tratado como definição autoritativa. Você desenha endpoints contra a especificação e mantém mocks, testes e documentação sincronizados com ela.

O ponto importante é a sincronização bidirecional com Git. O Apidog pode ler a especificação do repositório e gravar mudanças de volta nele. Assim:

• quem prefere editar visualmente pode usar a interface;
• quem prefere YAML pode editar direto no repositório;
• ambos os fluxos convergem para o mesmo arquivo commitado;
• a revisão por PR continua sendo o gate principal.

Para ver o fluxo de envio de mudanças ao GitHub, consulte como sincronizar sua especificação OpenAPI com o GitHub.

O resultado esperado: o OpenAPI permanece como fonte de verdade, e as ferramentas visuais complementam o processo em vez de substituí-lo.

Armadilhas comuns

Spec-as-code é simples, mas algumas decisões erradas reduzem seu valor.

1. Não validar implementação contra especificação

Escrever o OpenAPI não basta. Se a API real não for validada contra ele, contrato e implementação podem divergir.

Ação prática:

• adicione validação OpenAPI no CI;
• rode testes de contrato contra ambiente de teste;
• bloqueie merge ou deploy quando houver incompatibilidade.

2. Misturar fonte gerada e fonte escrita à mão

Escolha uma direção:

• ou a especificação é escrita como fonte de verdade;
• ou ela é gerada a partir do código.

Misturar as duas abordagens cria conflito. Ninguém sabe se deve alterar o YAML, as anotações no código ou ambos.

Se você adotar spec-as-code, trate openapi.yaml como fonte primária.

3. Usar a especificação só como documentação

Uma especificação apenas lida por humanos é documentação. Uma especificação usada para gerar mocks, testes, docs e SDKs é contrato.

Ação prática:

• conecte pelo menos uma saída automatizada no início;
• comece por documentação ou mock;
• depois adicione validação e testes de contrato.

4. Fazer merge sem revisão

Um arquivo OpenAPI no Git sem revisão é só um arquivo no Git.

Ação prática:

• exija PR para mudanças em api/openapi.yaml;
• adicione revisores responsáveis por contrato;
• use CI para lint e validação estrutural.

Como começar

Você pode adotar spec-as-code de forma incremental.

1. Coloque a especificação no repositório

Crie um caminho previsível:

api/openapi.yaml

Faça o commit inicial:

git add api/openapi.yaml
git commit -m "Add OpenAPI specification"

2. Revise mudanças por PR

Toda alteração de contrato deve passar pelo mesmo processo do código.

Exemplo de checklist para revisão:

• [ ] endpoint tem operationId;
• [ ] parâmetros obrigatórios estão claros;
• [ ] respostas de erro estão documentadas;
• [ ] schemas reutilizáveis estão em components;
• [ ] mudança é compatível com clientes existentes;
• [ ] versão da API foi atualizada quando necessário.

3. Adicione lint no CI

Valide a especificação em cada PR. O objetivo é impedir OpenAPI inválido antes do merge.

Um fluxo genérico:

name: Validate OpenAPI

on:
  pull_request:
    paths:
      - "api/openapi.yaml"

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate OpenAPI
        run: |
          echo "Execute aqui seu validador OpenAPI"

4. Gere uma saída

Comece com algo simples:

• documentação;
• mock server;
• coleção de testes;
• SDK.

O importante é que a saída dependa do arquivo commitado.

5. Feche o ciclo com testes de contrato

Depois que a especificação já estiver no fluxo do time, valide a API real contra ela. Isso transforma o OpenAPI em contrato executável.

Conclusão

Spec-as-code muda o contrato da API de “documento que alguém atualiza” para “artefato versionado que governa o desenvolvimento”.

O fluxo recomendado é:

1. manter openapi.yaml no Git;
2. revisar mudanças via PR;
3. validar a especificação no CI;
4. gerar mocks, docs, testes e SDKs;
5. testar a implementação contra o contrato.

A mudança é pequena no processo, mas grande no impacto: um arquivo, versionado como código, servindo como fonte de verdade para tudo a jusante.

Se você quer edição visual com sincronização Git integrada, experimente o Modo Spec-First do Apidog e mantenha seu arquivo OpenAPI como contrato central da API.

FAQ

“Especificação de API como código” é o mesmo que “docs-as-code”?

Não exatamente. As duas práticas compartilham a mesma filosofia: manter artefatos no controle de versão e publicá-los pelo pipeline normal.

Docs-as-code aplica isso à documentação. Spec-as-code aplica isso ao contrato da API. Quando a documentação é gerada a partir de uma especificação commitada, as duas práticas se complementam.

Qual formato devo usar para o arquivo de especificação?

OpenAPI em YAML é a escolha mais comum. YAML gera diffs legíveis em pull requests e continua sendo processável por ferramentas.

JSON também funciona, mas YAML costuma ser mais fácil de revisar manualmente.

Como evito que a especificação se desvie da API real?

Adicione testes de contrato no CI. Eles devem verificar se o serviço em execução corresponde à especificação commitada.

Se um endpoint remover um campo documentado, retornar um campo inesperado ou mudar um status code sem atualizar o contrato, a build deve falhar. Isso transforma a especificação em contrato imposto, não apenas documentação esperançosa.