Spec-First ou Design-First: Qual Modo Apidog Usar?

O módulo de APIs do Apidog permite criar o mesmo artefato de duas formas: um contrato de API em OpenAPI. Você pode usar formulários visuais no modo Design-First ou editar YAML/JSON diretamente no modo Spec-First com Git. A melhor escolha depende do fluxo de trabalho da sua equipe: colaboração visual ou especificação como código.

Experimente o Apidog hoje

Este guia mostra como escolher entre Design-First e Spec-First no Apidog, como cada modo lida com Git e quando usar cada um. Você alterna entre eles por um botão no canto inferior esquerdo do módulo de APIs, então a decisão não é permanente.

As duas abordagens

Em ambos os modos, a regra é a mesma: o contrato da API vem antes da implementação.

Esse contrato define:

• endpoints;
• métodos HTTP;
• parâmetros;
• corpos de requisição;
• respostas;
• schemas;
• exemplos;
• documentação;
• mocks;
• testes.

A diferença está em como você edita esse contrato.

Design-First

No Design-First, você cria o contrato por uma interface visual. Em vez de escrever OpenAPI manualmente, você adiciona endpoints, parâmetros e schemas usando formulários, menus e editores estruturados.

Use quando você quer:

• reduzir erros de sintaxe;
• permitir colaboração com PMs, QA e devs menos familiarizados com OpenAPI;
• criar APIs rapidamente do zero;
• revisar mudanças de forma visual.

Spec-First

No Spec-First, você escreve o contrato diretamente como OpenAPI ou Swagger em YAML/JSON. A especificação é tratada como código-fonte.

Use quando você quer:

• manter a spec no Git;
• revisar alterações via pull request;
• versionar o contrato junto com o serviço;
• aplicar linting/validação em CI;
• trabalhar diretamente com arquivos YAML/JSON.

Na prática, “spec-first” e “contract-first” costumam significar a mesma coisa: a especificação vem antes do código. A distinção importante no Apidog é operacional: um modo usa formulários, o outro usa editor de código.

Para uma visão mais ampla sobre especificações versionadas, veja o guia sobre fluxo de trabalho de API nativo do Git.

Modo Design-First do Apidog

O Modo Design-First é o designer visual do Apidog. Você constrói endpoints por uma interface guiada:

1. escolha o método HTTP;
2. defina o path;
3. adicione parâmetros de path, query, header ou cookie;
4. configure o body da requisição;
5. defina schemas de resposta;
6. adicione exemplos;
7. gere documentação, mocks e testes a partir do contrato.

Exemplo de fluxo para criar um endpoint:

GET /users/{id}

No Design-First, você configuraria:

• id como parâmetro de path;
• resposta 200 com schema User;
• resposta 404 com schema Error;
• exemplos de payload para documentação e mock.

Exemplo de schemas que poderiam ser modelados visualmente:

{
  "User": {
    "type": "object",
    "required": ["id", "name", "email"],
    "properties": {
      "id": {
        "type": "string"
      },
      "name": {
        "type": "string"
      },
      "email": {
        "type": "string",
        "format": "email"
      }
    }
  },
  "Error": {
    "type": "object",
    "required": ["code", "message"],
    "properties": {
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      }
    }
  }
}

A vantagem é que o Apidog valida a estrutura enquanto você trabalha. Isso reduz problemas como:

• YAML inválido;
• tipos incorretos;
• campos obrigatórios mal definidos;
• schemas duplicados;
• respostas incompletas.

O modo também oferece suporte a branches dentro do Apidog. Isso permite trabalhar em versões paralelas do design da API e revisar mudanças estruturadas em vez de diffs de texto bruto.

A limitação é que você trabalha por uma abstração. Se sua equipe já pensa diretamente em OpenAPI, os formulários podem parecer etapas extras.

Modo Spec-First do Apidog

O Modo Spec-First, atualmente em beta, substitui os formulários por um editor de código estilo IDE. Nele, você escreve OpenAPI ou Swagger diretamente em YAML ou JSON.

Exemplo de contrato OpenAPI editado manualmente:

openapi: 3.0.3
info:
  title: Users API
  version: 1.0.0

paths:
  /users/{id}:
    get:
      summary: Buscar usuário por ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Usuário encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: Usuário não encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string

O editor inclui:

• destaque de sintaxe;
• validação em linha;
• autocompletar para OpenAPI/Swagger;
• navegação automática por paths e components;
• indicador de sincronização com o repositório conectado.

O principal recurso é a sincronização Git bidirecional.

Você pode:

1. conectar um repositório GitHub, GitLab ou Azure DevOps via Git Connection;
2. editar a especificação no Apidog;
3. fazer commit e push pelo aplicativo;
4. editar o mesmo arquivo no seu editor local;
5. fazer push no Git;
6. puxar as mudanças de volta para o Apidog.

Assim, o arquivo OpenAPI continua sendo a fonte única da verdade.

Exemplo de fluxo prático:

git checkout -b add-users-endpoint

Edite o arquivo:

openapi.yaml

Faça commit:

git add openapi.yaml
git commit -m "Add users endpoint contract"
git push origin add-users-endpoint

Depois, revise a alteração em pull request e sincronize com o Apidog.

A configuração completa está na documentação do Modo Spec-First.

Se sua equipe já trata infraestrutura, configuração e contratos como código, veja também o artigo sobre especificação de API como código.

Comparação lado a lado

Critério	Modo Design-First	Modo Spec-First (beta)
Editor	Formulários visuais e árvore de schemas	Editor YAML/JSON estilo IDE
Formato	OpenAPI gerado pelo Apidog	OpenAPI/Swagger escrito manualmente
Git	Branches dentro do Apidog	Sincronização bidirecional com GitHub, GitLab e Azure DevOps via Git Connection
Validação	Imposta pelos formulários	Validação em linha e autocompletar
Navegação	Lista de endpoints e pastas	Estrutura analisada na barra lateral
Curva de aprendizado	Baixa	Maior
Melhor para	Times multidisciplinares	Times que tratam spec como código
Revisão	Visual e estruturada	Diff linha a linha em PR
Risco comum	Menos controle direto sobre YAML	Erros manuais de especificação

Quando escolher Design-First

Escolha o Modo Design-First se:

• nem todos no time dominam OpenAPI;
• PMs, QA ou suporte precisam revisar contratos;
• você está iniciando uma API do zero;
• quer criar endpoints rapidamente;
• prefere validação guiada;
• quer reduzir erros de sintaxe;
• a revisão visual é mais útil que diff em YAML.

Fluxo recomendado:

1. crie o endpoint visualmente;
2. defina parâmetros e schemas;
3. adicione exemplos;
4. gere mock para validar o comportamento esperado;
5. compartilhe a documentação com o time;
6. revise o contrato antes da implementação.

Quando escolher Spec-First

Escolha o Modo Spec-First se:

• sua especificação já vive no Git;
• mudanças de API passam por pull requests;
• você executa validação de OpenAPI em CI;
• quer versionar contrato e serviço juntos;
• prefere editar YAML/JSON diretamente;
• usa o mesmo arquivo de spec em múltiplas ferramentas.

Fluxo recomendado:

1. conecte o repositório Git ao Apidog;
2. selecione o arquivo OpenAPI/Swagger;
3. edite a spec no Apidog ou no seu editor local;
4. valide a estrutura;
5. faça commit e push;
6. revise a alteração em PR;
7. sincronize de volta no Apidog.

Exemplo de validação em CI, se sua equipe já usa ferramentas externas de linting OpenAPI:

name: Validate OpenAPI

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

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate OpenAPI spec
        run: |
          npx @redocly/cli lint openapi.yaml

Caminho híbrido

Você não precisa escolher um único modo para sempre.

Um fluxo comum é:

1. usar Design-First para desenhar endpoints novos rapidamente;
2. validar estrutura, exemplos e respostas com o time;
3. alternar para Spec-First quando o contrato amadurecer;
4. conectar a spec ao Git;
5. revisar mudanças futuras por pull request.

Isso funciona porque os dois modos representam o mesmo contrato subjacente. A diferença é a interface de edição.

Como alternar entre os modos

Para mudar de modo:

1. abra seu projeto no Apidog;
2. entre no módulo de APIs;
3. vá até o canto inferior esquerdo;
4. use o seletor de modo;
5. alterne entre Design-First e Spec-First.

Ao alternar:

• endpoints são mantidos;
• schemas são mantidos;
• exemplos são mantidos;
• o contrato subjacente continua o mesmo;
• apenas a superfície de edição muda.

Se você for usar o Spec-First com Git:

1. conecte seu repositório GitHub, GitLab ou Azure DevOps;
2. selecione o arquivo OpenAPI/Swagger;
3. confirme o estado de sincronização;
4. teste o fluxo de commit, push e pull;
5. só depois use em contratos críticos de produção.

Como o Spec-First está em beta, valide o comportamento em um projeto controlado antes de adotá-lo como padrão.

FAQ

Spec-first é o mesmo que contract-first?

Na prática, sim. Ambos significam que a especificação da API é criada antes da implementação e usada como fonte da verdade. No Apidog, o Modo Spec-First representa esse fluxo por meio de um arquivo OpenAPI ou Swagger editado manualmente e sincronizado com Git.

O Modo Spec-First funciona com GitLab e Azure DevOps?

Sim. O Modo Spec-First suporta sincronização Git bidirecional com GitHub e GitLab. O Azure DevOps funciona por meio de uma Git Connection genérica.

Posso alternar do Design-First para o Spec-First sem perder meu trabalho?

Sim. Os dois modos leem e escrevem o mesmo contrato subjacente. Ao alternar pelo botão no canto inferior esquerdo do módulo de APIs, seus endpoints, schemas e exemplos permanecem intactos.

Qual modo devo usar para uma API nova?

Se o time precisa colaborar rapidamente e nem todos dominam OpenAPI, comece com Design-First. Se a especificação já precisa nascer no Git e passar por pull request, comece com Spec-First.

Qual modo é melhor para revisão de mudanças?

Depende do público da revisão.

Use Design-First para revisões visuais com stakeholders técnicos e não técnicos. Use Spec-First quando a revisão acontece principalmente em pull requests, com diffs linha a linha.

Conclusão

Use Design-First quando a prioridade for velocidade, colaboração visual e menor curva de aprendizado.

Use Spec-First quando a prioridade for Git, pull requests, CI e especificação como código.

Os dois modos produzem OpenAPI válido e alimentam os mesmos fluxos downstream de documentação, mocks e testes. A decisão não é sobre qual contrato criar, mas sobre como sua equipe prefere editá-lo.

Para decidir na prática, abra o módulo de APIs, alterne o modo no canto inferior esquerdo e modele o mesmo endpoint das duas formas. O contrato será o mesmo; escolha a interface que reduz atrito no fluxo diário da sua equipe.