DEV Community

Cover image for Segurança da Documentação API: Sua Especificação Está Segura no Git?
Lucas
Lucas

Posted on • Originally published at apidog.com

Segurança da Documentação API: Sua Especificação Está Segura no Git?

A segurança da documentação da API costuma ficar fora das auditorias. A API recebe autenticação, rate limit e testes; já a especificação OpenAPI, o Swagger UI e os guias de autenticação muitas vezes ficam em um repositório Git ou host estático sem revisão contínua. Em 20 de maio de 2026, o GitHub confirmou que invasores roubaram dados de cerca de 3.800 repositórios internos após uma extensão VS Code maliciosa ser instalada no laptop de um funcionário. Use esse incidente como gatilho para uma checagem prática: se alguém alterasse silenciosamente sua documentação publicada, você perceberia antes que seus consumidores copiassem endpoints, tokens ou fluxos errados para produção?

Experimente o Apidog hoje

TL;DR

Documentação de API segura precisa de quatro propriedades verificáveis:

  • Controle de acesso: quem pode ler a documentação.
  • Versionamento: qual versão da API cada consumidor está usando.
  • Integridade: se o conteúdo publicado corresponde à fonte aprovada.
  • Trilha de auditoria: quem alterou o quê e quando.

Docs-as-code no Git funciona bem para APIs públicas e pipelines disciplinados. Vira risco quando o repositório é público sem controle de acesso, quando a especificação diverge da API real ou quando um exemplo adulterado chega aos consumidores sem detecção.

Uma camada gerenciada como o Apidog adiciona proteção por senha, listas de permissões por IP e e-mail, domínio personalizado, versionamento e documentação sincronizada com o design da API como fonte da verdade.

Por que a violação do GitHub deve fazer você revisar sua documentação de API

Antes de mudar sua arquitetura, entenda o alerta. Segundo a cobertura do BleepingComputer, o grupo TeamPCP exfiltrou repositórios internos do GitHub e colocou o conjunto de dados à venda. A extensão maliciosa veio do marketplace oficial do VS Code e foi executada no dispositivo de um funcionário. O GitHub informou que não encontrou evidências de dados de clientes afetados fora dos repositórios internos, e a investigação continuava em andamento.

O ponto para equipes de API é direto: sua documentação também é uma superfície de ataque.

Muitas equipes publicaram um Swagger UI no GitHub Pages, apontaram um CNAME e nunca mais revisaram o fluxo. O repositório é público. O último merge vira a documentação ativa. Commits de documentação recebem menos atenção do que código de produção.

Isso é perigoso porque documentação de API é instrução executável para outros desenvolvedores. Consumidores copiam:

  • URLs de endpoints
  • payloads de exemplo
  • cabeçalhos de autenticação
  • fluxos OAuth
  • exemplos de token
  • snippets de código

Se um invasor muda essas instruções, ele não está apenas alterando texto. Ele está influenciando código que será executado em produção.

Esse padrão aparece em outros incidentes: uma pequena mudança em uma superfície confiável pode se propagar. Veja também nosso artigo sobre lições de segurança de API da violação da Vercel.

Este guia cobre:

  1. Como documentação comprometida prejudica consumidores de API.
  2. Quando docs-as-code no Git é adequado.
  3. Quando docs-as-code vira risco.
  4. Como aplicar uma checklist de documentação segura.
  5. Como o Apidog ajuda a fechar lacunas de controle de acesso, versionamento e integridade.

Para temas relacionados, veja também:

O que pode dar errado quando sua documentação é comprometida

Modele sua documentação como uma cadeia:

Fonte da documentação
        ↓
Repositório Git
        ↓
Pipeline de build
        ↓
Host publicado
        ↓
Consumidor da API
Enter fullscreen mode Exit fullscreen mode

Se qualquer etapa for comprometida, os consumidores podem receber instruções erradas.

1. Um endpoint adulterado pode chegar ao código de produção

Exemplo: sua documentação mostra este endpoint:

https://api.payments.acme.com/v2/charge
Enter fullscreen mode Exit fullscreen mode

Um invasor altera para:

https://api-payments-acme.example.net/v2/charge
Enter fullscreen mode Exit fullscreen mode

A página continua renderizando. O YAML continua válido. O CI pode continuar verde. Mas o próximo consumidor que copiar o endpoint pode enviar dados sensíveis para o domínio errado.

O mesmo vale para uma especificação OpenAPI:

paths:
  /v2/payment-intents:
    post:
      summary: Create a payment intent
      servers:
        - url: https://api.acme-pay.com
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentRequest'
      responses:
        '201':
          description: Payment intent created
Enter fullscreen mode Exit fullscreen mode

Uma alteração mínima no campo servers.url pode redirecionar clientes gerados automaticamente:

 servers:
-  - url: https://api.acme-pay.com
+  - url: https://api-acme-pay.example.net
Enter fullscreen mode Exit fullscreen mode

Se seus consumidores geram SDKs a partir da especificação, o risco aumenta:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Uma especificação adulterada pode virar cliente adulterado.

2. Endpoints internos podem vazar

Repositórios de documentação acumulam rotas que não deveriam ser públicas:

paths:
  /admin/users:
    get:
      summary: Internal admin user list

  /debug/session:
    post:
      summary: Debug session inspector

  /partners/reconcile:
    post:
      summary: Partner-only reconciliation endpoint
Enter fullscreen mode Exit fullscreen mode

Se o repositório for público, esses endpoints viram um mapa para atacantes.

Mesmo se o repositório for privado, uma violação pode expor a especificação inteira. O invasor passa a conhecer:

  • rotas
  • parâmetros
  • formatos de payload
  • nomes de headers
  • esquemas de autenticação
  • endpoints de administração ou parceiros

Para revisar esse tipo de superfície antes que alguém faça isso por você, use uma checklist como a lista de verificação de testes de segurança de API para 2026.

3. GitHub Pages público não é controle de acesso

GitHub Pages é ótimo para documentação pública. Mas ele não controla quem lê.

Se sua documentação é destinada apenas a clientes, parceiros ou times internos, um URL “difícil de adivinhar” não basta.

URLs vazam por:

  • histórico do navegador
  • headers Referer
  • logs de proxy
  • favoritos compartilhados
  • chats internos
  • ferramentas de analytics
  • tickets de suporte

Se qualquer pessoa com o link consegue acessar, isso não é documentação privada.

4. Documentação desatualizada também é um problema de segurança

Nem todo incidente exige um invasor.

Às vezes a API muda e a documentação não:

- POST /v1/users
+ POST /v2/users
Enter fullscreen mode Exit fullscreen mode

Ou o payload muda:

 {
-  "name": "Ana"
+  "fullName": "Ana Silva"
 }
Enter fullscreen mode Exit fullscreen mode

Quando a documentação diverge da API real, consumidores implementam contra um contrato falso. Se a documentação também pode ser adulterada, fica ainda pior: você não sabe se o erro é drift operacional ou alteração maliciosa.

Pergunta prática:

Se um endpoint mudou na documentação publicada há uma hora, você consegue provar quem mudou, por qual revisão e a partir de qual fonte?

Se não, sua documentação não é verificável.

Quando docs-as-code no Git é uma boa escolha

Docs-as-code é uma prática válida. Manter OpenAPI e Markdown no Git pode funcionar muito bem quando há disciplina.

Um fluxo comum:

openapi.yaml
docs/*.md
        ↓
Pull Request
        ↓
Review obrigatório
        ↓
CI valida a especificação
        ↓
Build do Swagger UI ou Redoc
        ↓
Deploy em host estático
Enter fullscreen mode Exit fullscreen mode

Ferramentas como Redoc funcionam bem nesse modelo.

Use docs-as-code quando:

  • a API é totalmente pública;
  • não há endpoints internos no repositório publicado;
  • branches são protegidas;
  • PRs exigem revisão;
  • commits de documentação são revisados com o mesmo rigor do código;
  • o pipeline usa dependências e actions fixadas;
  • secrets de deploy têm escopo mínimo;
  • a especificação é validada contra a API real;
  • alguém é dono da atualização da documentação.

Exemplo de validação mínima no CI:

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
Enter fullscreen mode Exit fullscreen mode

Você também pode bloquear alterações sensíveis com revisão extra:

name: Detect sensitive OpenAPI changes

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

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

      - name: Show changed server URLs
        run: |
          git fetch origin main
          git diff origin/main...HEAD -- openapi.yaml | grep -E "servers:|url:" || true
Enter fullscreen mode Exit fullscreen mode

Isso não substitui revisão humana, mas ajuda a destacar mudanças que merecem atenção.

Quando docs-as-code vira risco

O mesmo modelo começa a falhar quando uma destas condições aparece:

  • a documentação deveria ser privada, mas está em host público;
  • endpoints internos estão misturados com endpoints públicos;
  • muitas pessoas ou contas de serviço têm acesso de escrita;
  • PRs de documentação são aprovados automaticamente;
  • tokens de CI e deploy não são auditados;
  • a especificação é editada manualmente e diverge da API;
  • ninguém valida se o site publicado corresponde à fonte revisada;
  • não há logs confiáveis da etapa de deploy.

A violação do GitHub se encaixa nesse alerta. O Git dá histórico e transparência, mas não garante confidencialidade se o repositório for exfiltrado.

Para comparar abordagens de documentação auto-hospedada, veja a comparação de documentação de API auto-hospedada.

Resumo prático:

  • mantenha docs-as-code se sua API é pública e seu pipeline é controlado;
  • reconsidere se você precisa de acesso restrito, versionamento gerenciado ou garantia de que a documentação publicada vem da fonte correta.

Checklist: o que “documentação de API segura” significa

Use esta checklist para auditar sua configuração atual.

1. Controle de acesso

Perguntas:

  • A documentação é pública de propósito?
  • Quem consegue acessá-la hoje?
  • Você consegue revogar acesso em menos de um minuto?
  • Clientes, parceiros e times internos têm níveis diferentes de acesso?
  • Existe senha, allowlist de IP, allowlist de e-mail ou SSO?

Sinal de risco:

“Ela é privada porque ninguém tem o link.”
Enter fullscreen mode Exit fullscreen mode

Isso não é controle de acesso.

2. Versionamento

Perguntas:

  • A documentação da API v1 continua disponível?
  • A documentação da v2 está separada da v1?
  • Consumidores antigos conseguem encontrar o contrato correto?
  • Você sabe o que a documentação dizia em uma data específica?

Estrutura recomendada:

/docs/v1
/docs/v2
/docs/beta
Enter fullscreen mode Exit fullscreen mode

Ou versões publicadas lado a lado em uma plataforma de documentação.

3. Integridade

Perguntas:

  • A documentação publicada vem de uma fonte controlada?
  • Existe revisão antes de publicar?
  • Alterações em servers.url, autenticação e exemplos de token recebem atenção especial?
  • Você consegue detectar diferença entre fonte revisada e site publicado?

Exemplo de campos que merecem revisão cuidadosa em OpenAPI:

servers:
  - url: https://api.example.com

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

paths:
  /oauth/token:
    post:
      summary: Exchange authorization code for access token
Enter fullscreen mode Exit fullscreen mode

4. Trilha de auditoria

Perguntas:

  • Quem alterou a documentação?
  • O que mudou?
  • Quando mudou?
  • Quem aprovou?
  • Qual versão foi publicada?
  • O deploy foi feito por qual pipeline ou usuário?

O Git cobre parte disso no repositório. Mas você também precisa de rastreabilidade na publicação.

Como o Apidog ajuda a implementar documentação segura

Apidog é uma plataforma de API para projetar, depurar, testar, simular e documentar APIs. Para acompanhar na prática, baixe o Apidog e abra um projeto com uma definição de API.

1. Publique documentação a partir de uma fonte controlada

No Apidog, a documentação é gerada a partir do design da API no projeto. Você define endpoints, schemas e autenticação, e o Apidog gera automaticamente a documentação.

Fluxo básico:

Design da API no Apidog
        ↓
Endpoints, schemas e auth
        ↓
Publicar documentação
        ↓
Site interativo com exemplos e console de teste
Enter fullscreen mode Exit fullscreen mode

A vantagem é reduzir drift. A documentação não precisa ser um Markdown solto que evolui separado da definição da API.

2. Aplique controle de acesso real

Ao publicar documentação no Apidog, você pode escolher métodos de acesso:

  • Público: qualquer pessoa com o link pode ler.
  • Proteção por senha: acesso mediante senha compartilhada.
  • Lista de permissões de IP: restrição por IPs ou faixas, como escritório ou VPN.
  • Lista de permissões de e-mail: acesso por e-mails ou domínios permitidos.
  • Login personalizado: autenticação própria com JWT emitido pelo seu servidor.

Exemplo de regra por domínio:

*@suaempresa.com
Enter fullscreen mode Exit fullscreen mode

Isso permite cobrir uma organização inteira sem cadastrar cada usuário manualmente.

O Apidog documenta essas opções no guia para controlar o acesso à documentação da API.

3. Use domínio personalizado

Você pode publicar a documentação em um domínio próprio, como:

developer.suaempresa.com
Enter fullscreen mode Exit fullscreen mode

O Apidog suporta domínio personalizado via CNAME DNS ou proxy reverso.

Domínio personalizado não substitui autenticação, mas ajuda a manter a documentação em uma superfície governada pela sua organização.

4. Mantenha OpenAPI sincronizado com o design da API

O Apidog trata o design da API como fonte da verdade e mantém a documentação sincronizada com ele.

Ele importa:

  • OpenAPI 3.0
  • OpenAPI 3.1
  • Swagger 2.0

Também suporta importações programadas para manter uma especificação externa atualizada.

Se hoje você mantém um openapi.yaml manualmente no Git, revise se ele ainda representa a API real. Equipes que vêm do SwaggerHub podem usar o guia para migrar documentação de API do SwaggerHub para o Apidog.

5. Publique múltiplas versões

O Apidog suporta versionamento da documentação. Isso permite manter versões lado a lado:

API v1 → documentação v1
API v2 → documentação v2
API beta → documentação beta
Enter fullscreen mode Exit fullscreen mode

Isso evita que consumidores da v1 leiam, sem perceber, instruções da v2.

Comparação rápida de opções

Propriedade GitHub Pages Público (Swagger UI / Redoc) Docs auto-hospedados em seu próprio servidor Docs gerenciados (Apidog)
Controle de acesso Nenhum; apenas obscuridade de URL O que você construir e mantiver Embutido: senha, IP, e-mail, login personalizado
Versionamento Manual; builds ou branches separadas Manual Embutido; versões publicadas lado a lado
Integridade Revisão + histórico do Git, se imposto Depende do seu pipeline Docs gerados a partir do design de API controlado
Trilha de auditoria Histórico do Git para o repositório, não para a implantação Depende do seu logging Histórico de mudanças no design e na documentação publicada
Custo de manutenção Baixo para configurar, mas exige manutenção contínua do pipeline Alto; você mantém toda a pilha Baixo; a plataforma cuida da hospedagem e dos portões
Melhor adequação APIs totalmente públicas com pipeline disciplinado Equipes com requisitos estritos de auto-hospedagem Equipes que precisam de controle de acesso sem sobrecarga operacional

Não existe uma resposta universal.

Use GitHub Pages público quando:

  • a API é realmente pública;
  • a especificação não contém endpoints internos;
  • o pipeline é revisado e protegido.

Use auto-hospedagem quando:

  • há requisitos rígidos de residência, isolamento ou infraestrutura;
  • sua equipe consegue manter autenticação, logs, CI/CD e hardening.

Use uma camada gerenciada quando:

  • você precisa restringir acesso rapidamente;
  • quer versionamento sem manter infraestrutura;
  • precisa reduzir drift entre design e documentação publicada.

Para aprofundar a comparação, veja:

Plano de ação para auditar sua documentação

Execute esta revisão em uma sessão curta com o time de API.

1. Liste todos os locais publicados 

- GitHub Pages
- Swagger UI interno
- Redoc público
- Portal de desenvolvedores
- Wiki interna
- Postman collection pública
- Repositórios com openapi.yaml
- PDFs ou guias antigos
Enter fullscreen mode Exit fullscreen mode

2. Classifique cada documentação 

Pública
Parceiros
Clientes
Interna
Restrita por produto/plano
Enter fullscreen mode Exit fullscreen mode

3. Verifique controle de acesso

Para cada item, responda:

Quem pode ler?
Como revogar acesso?
Existe autenticação real?
Existe senha, IP allowlist, e-mail allowlist ou SSO?
Enter fullscreen mode Exit fullscreen mode

4. Verifique integridade 

Qual é a fonte da verdade?
Quem aprova mudanças?
O site publicado corresponde à fonte?
Mudanças em endpoints e auth são revisadas?
Enter fullscreen mode Exit fullscreen mode

5. Verifique versionamento 

A v1 ainda tem documentação própria?
A v2 sobrescreveu a v1?
Consumidores antigos sabem qual versão usar?
Enter fullscreen mode Exit fullscreen mode

6. Verifique trilha de auditoria 

Consigo ver alterações dos últimos 90 dias?
Consigo identificar autor e aprovador?
Consigo saber quando uma versão foi publicada?
Enter fullscreen mode Exit fullscreen mode

Conclusão

A violação do GitHub não é motivo para abandonar docs-as-code ou deixar de usar GitHub. Ela é um lembrete para auditar uma superfície que muitos times ignoram: a documentação da API.

Seu próximo passo:

  1. Liste onde sua documentação está publicada.
  2. Classifique cada publicação por público.
  3. Valide controle de acesso, versionamento, integridade e auditoria.
  4. Corrija primeiro a maior lacuna.

Se a lacuna principal for controle de acesso, teste publicar a documentação de um projeto no Apidog com senha, allowlist de IP ou allowlist de e-mail. Isso permite transformar documentação de API de “site estático esquecido” em uma superfície governada e verificável.

Top comments (0)