Como Converter OpenAPI para Documentação Markdown Limpa Automaticamente

Seu arquivo OpenAPI é a fonte da verdade para sua API. Ele lista cada caminho, cada parâmetro, cada formato de resposta. O problema é que quase ninguém em sua equipe quer ler YAML ou JSON puro. Um engenheiro de backend quer uma referência rápida de endpoint no repositório. Um desenvolvedor frontend quer uma tabela de campos de requisição que ele possa escanear em um pull request. Um escritor técnico quer algo que possa colar em um wiki sem precisar redigitar todo o esquema.

Markdown é o formato que se adapta a todos esses leitores. Ele renderiza no GitHub, no Confluence, em um gerador de site estático e em um editor de texto simples. Então, a tarefa recorrente é esta: pegar um openapi.yaml que já existe e transformá-lo em Markdown limpo que as pessoas realmente abram. Fazer isso manualmente é lento e o conteúdo se desatualiza no momento em que alguém adiciona um endpoint. Fazer isso automaticamente é a única versão que sobrevive ao contato com um ciclo de lançamento real.

Por que gerar Markdown a partir do OpenAPI

Um documento OpenAPI é construído para máquinas. Ferramentas o analisam para gerar clientes, executar testes de contrato, validar requisições e renderizar documentações interativas. Essa legibilidade por máquina é o ponto principal, e vale a pena protegê-la. Se você quer um lembrete sobre como manter a especificação correta, o guia de ferramentas de validação OpenAPI aborda a linting antes mesmo de você gerar qualquer coisa a partir dela.

Markdown resolve um problema diferente: distribuição para humanos em lugares que não executam um renderizador OpenAPI. Alguns casos concretos surgem repetidamente.

• Um README.md ou pasta /docs no repositório, para que um novo colaborador veja a lista de endpoints sem sair da base de código.
• Uma descrição de pull request que precisa mostrar o que um novo endpoint aceita e retorna.
• Uma página no Confluence ou Notion onde a equipe mais ampla, incluindo não-engenheiros, revisa o contrato.
• Um site de documentação estática construído com Docusaurus, MkDocs ou Hugo, todos os quais aceitam Markdown como entrada.

A palavra-chave é automaticamente. Um arquivo Markdown que você escreve uma vez e esquece estará errado no próximo sprint. Um arquivo Markdown regenerado a partir da especificação a cada mudança permanece fiel ao contrato gratuitamente. Essa é a diferença entre documentos em que as pessoas confiam e documentos que as pessoas aprendem a ignorar.

Os métodos de conversão, do rápido ao à prova de balas

Não existe um único comando oficial que venha com o OpenAPI para produzir Markdown. Em vez disso, há um pequeno ecossistema de conversores, além dos motores de documentação incorporados às plataformas de API. Aqui está o panorama, ordenado aproximadamente pela quantidade de configuração que cada um exige.

Escolha com base na quantidade de controle que você precisa e onde a saída deve ser entregue. As próximas seções mostram cada um funcionando.

Método 1: um conversor open-source de uma linha

O caminho mais rápido é um conversor dedicado. Dois bem conhecidos cobrem os mundos Node e Python.

Para um projeto Node, openapi-to-md pega um documento v2 ou v3 em YAML ou JSON e escreve um arquivo Markdown estruturado. Você pode executá-lo sem uma instalação global:

npx openapi-to-md openapi.yaml api-reference.md

Para uma ferramenta Python, openapi-markdown faz o mesmo trabalho com uma instalação pip e um único comando:

pip install openapi-markdown
openapi2markdown openapi.yaml api-reference.md

Ambos leem a especificação, percorrem cada caminho e esquema, e emitem um arquivo Markdown com cabeçalhos por endpoint e tabelas para parâmetros e respostas. O argumento do arquivo de saída é opcional em algumas dessas ferramentas; deixe-o de fora e eles usarão o nome de entrada com uma extensão .md por padrão. Isso é suficiente para uma referência de repositório que você regenera sob demanda.

A desvantagem dos conversores rápidos é o controle do layout. Você obtém a estrutura deles, não a sua. Se as tabelas padrão deles correspondem à forma como sua equipe lê documentos, você termina em uma linha. Se você precisa de exemplos de código em cinco linguagens ou uma ordem de seção específica, você quer o próximo método.

Método 2: Widdershins para documentos tematizáveis com exemplos de código

Widdershins é a ferramenta Node estabelecida para transformar um arquivo OpenAPI ou Swagger em Markdown compatível com Slate. É a ferramenta a ser usada quando você deseja abas de código de linguagem e um template personalizável, e quando o Markdown alimenta um gerador de site estático como Docusaurus ou MkDocs.

Instale-o e execute a conversão básica:

npm install -g widdershins
widdershins openapi.yaml -o api-reference.md

Adicione linguagens de exemplo de código e remova o cabeçalho front-matter quando estiver enviando a saída para algum lugar que adicione o seu próprio:

widdershins --language_tabs 'shell:cURL' 'python:Python' 'javascript:JavaScript' \
  --omitHeader openapi.yaml -o api-reference.md

Widdershins usa um sistema de templates, então você pode sobrescrever o layout de qualquer seção em vez de aceitar o padrão. Isso o torna a ponte entre um "dump" bruto e um site de documentação totalmente construído à mão. O custo é que agora você é responsável por um template e uma etapa de construção, o que é bom para um repositório de documentação e excessivo para um README rápido.

Método 3: um script personalizado quando você precisa de um layout exato

Às vezes, nenhum dos conversores prontos produz o formato que você deseja. Talvez você precise de um arquivo Markdown por tag, ou um índice de endpoint compacto, ou tabelas de esquema que correspondam a um guia de estilo interno. Nesse caso, analise a especificação você mesmo e crie um template para a saída. A especificação é apenas dados estruturados, então isso é menos trabalho do que parece.

Uma versão mínima em Node que lista todas as operações se parece com isto:

import { readFileSync, writeFileSync } from "node:fs";
import yaml from "js-yaml";

const spec = yaml.load(readFileSync("openapi.yaml", "utf8"));
const lines = [`# ${spec.info.title}`, "", spec.info.description ?? "", ""];

for (const [path, methods] of Object.entries(spec.paths)) {
  for (const [method, op] of Object.entries(methods)) {
    lines.push(`## ${method.toUpperCase()} ${path}`);
    lines.push("");
    lines.push(op.summary ?? "");
    lines.push("");
    const params = op.parameters ?? [];
    if (params.length) {
      lines.push("| Name | In | Required | Description |");
      lines.push("| ---- | -- | -------- | ----------- |");
      for (const p of params) {
        lines.push(`| ${p.name} | ${p.in} | ${p.required ? "yes" : "no"} | ${p.description ?? ""} |`);
      }
      lines.push("");
    }
  }
}

writeFileSync("api-reference.md", lines.join("\n"));

São cerca de quarenta linhas para controle total sobre a saída. Você decide os títulos, as colunas da tabela, a divisão dos arquivos. A desvantagem é a manutenção: quando a versão do OpenAPI que você almeja adiciona um recurso, seu script tem que aprender. Para um estilo interno estável, essa troca geralmente vale a pena. Para uma ampla cobertura da especificação, apoie-se em um conversor mantido. Se você está avaliando se deve programar isso ou comprar, o resumo de geradores de documentação de API com exportação Markdown compara as opções mantidas lado a lado.

Método 4: Mantenha a especificação, os documentos e os testes juntos no Apidog

Os conversores acima compartilham um ponto cego. Eles transformam uma especificação em Markdown, e então os dois se separam. Alguém edita a API, esquece de rodar o conversor, e o Markdown mente. A solução é parar de tratar a especificação como um arquivo que vive sozinho e começar a tratá-la como parte de um ambiente de trabalho onde os documentos e testes se atualizam junto com ela.

Esse é o modelo que o Apidog usa. Você importa seu openapi.yaml existente, e o Apidog lê cada caminho, esquema e exemplo para um projeto. A partir daí, você obtém documentação de API renderizada e hospedada, gerada diretamente da especificação importada, sem uma etapa de construção separada. O fluxo de importação completo é coberto em como importar Swagger ou OpenAPI e gerar requisições, e o caminho da especificação para a referência publicada em gerar automaticamente documentação de API a partir do OpenAPI.

Duas coisas tornam isso diferente de um conversor de uso único.

Primeiro, a documentação suporta blocos de conteúdo Markdown próprios. A referência de endpoint gerada vem da especificação, e você sobrepõe Markdown escrito à mão em torno dela: uma página de primeiros passos, notas de autenticação, entradas de changelog. As dicas para criar documentação com Markdown do Apidog abordam essa parte de autoria. Assim, você não está escolhendo entre documentos gerados e escritos; você obtém ambos em um só lugar.

Em segundo lugar, a mesma especificação importada se torna a base para cenários de teste. Você constrói requisições e asserções contra os endpoints que a especificação define, e então os executa para provar que a API ativa ainda corresponde ao contrato que produziu seus documentos. Isso fecha o ciclo de desatualização: se a API muda e quebra o contrato, os testes falham, e você sabe que os documentos estão desatualizados antes mesmo que um leitor perceba.

Para acompanhar, baixe o Apidog, importe uma especificação e abra os documentos gerados no mesmo projeto. O ponto não é que o Apidog imprime um arquivo .md no disco. É que a especificação, os documentos legíveis por humanos e os testes que mantêm ambos honestos deixam de ser três arquivos desconectados.

Torne automático: regenere o Markdown em CI

Um conversor que você executa manualmente é um conversor que você esquece. Todo o valor de gerar Markdown a partir do OpenAPI aparece somente quando a geração ocorre por si só, a cada mudança. O padrão é simples: em cada push que toca na especificação, regenere o Markdown e o comite de volta, ou o publique.

Aqui está um job do GitHub Actions que regenera a referência sempre que openapi.yaml muda:

name: Gerar documentação da API

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

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - name: Converter especificação para Markdown
        run: npx openapi-to-md openapi.yaml docs/api-reference.md
      - name: Commitar documentos regenerados
        run: |
          git config user.name "docs-bot"
          git config user.email "docs-bot@users.noreply.github.com"
          git add docs/api-reference.md
          git diff --staged --quiet || git commit -m "docs: regenerar referência da API"
          git push

Agora, o Markdown nunca pode se desviar mais de um commit da especificação. A mesma ideia funciona no GitLab CI ou em qualquer executor com Node ou Python; basta trocar a etapa de conversão por widdershins ou seu script.

Há mais uma peça que vale a pena conectar. Documentos regenerados só são confiáveis se a especificação da qual eles vêm ainda for precisa. É aí que uma execução de teste em linha de comando ganha seu lugar no mesmo pipeline. O CLI do Apidog executa os cenários de teste que você construiu contra sua especificação importada, de forma headless, com um único comando:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Ele sai com um código diferente de zero se alguma asserção falhar, o que falha a build, o que impede você de publicar documentos que descrevem uma API que não se comporta mais dessa forma. A superfície completa de flags está na referência do comando apidog run, e a configuração mais ampla do pipeline no guia completo do Apidog CLI. Emparelhe a geração de documentos com um teste de contrato e os dois se reforçam: a especificação produz os documentos, e o teste prova a especificação.

Limpeza do Markdown gerado

O Markdown gerado raramente é perfeito na primeira tentativa. Alguns hábitos o mantêm legível.

• Remova o front matter gerado automaticamente quando o renderizador de destino não o desejar. Widdershins faz isso com --omitHeader; para outras ferramentas, um sed rápido sobre o arquivo funciona.
• Decida uma divisão de arquivos. Um arquivo Markdown gigante é bom para um README. Para um site de documentação, divida por tag ou recurso para que cada página seja curta.
• Mantenha os exemplos reais. A maioria dos conversores extrai os valores de exemplo diretamente da especificação, então a qualidade da sua documentação gerada acompanha a qualidade dos seus examples no OpenAPI. Melhores exemplos de entrada, melhor documentação de saída.
• Regenere, não edite manualmente. No momento em que você edita manualmente o Markdown gerado, a próxima conversão o sobrescreve. Coloque o conteúdo escrito à mão em arquivos separados e deixe o gerador ser responsável apenas pela seção de referência.

Se a sua própria especificação estiver bagunçada, corrija-a na fonte. Especificações mais limpas produzem documentos mais limpos, e o post ferramentas de validação OpenAPI mostra como fazer lint para as lacunas que produzem uma saída feia.

Escolhendo o método certo para sua equipe

Combine a ferramenta com o destino do Markdown e a quantidade de controle de que você precisa.

• Você quer uma referência de repositório em um comando e não se importa com o layout: use openapi-to-md ou openapi-markdown.
• Você está construindo um site de documentação com exemplos de código e quer um template tematizável: use Widdershins.
• Você tem um guia de estilo interno que os conversores não conseguem replicar: escreva um pequeno script sobre a especificação analisada.
• Você quer que os documentos, a especificação e os testes que os mantêm sincronizados vivam em um único espaço de trabalho, com saída hospedada e sem necessidade de acompanhar uma build separada: importe a especificação para o Apidog.

Estes não são mutuamente exclusivos. Muitas equipes usam o Apidog como a fonte da verdade para a especificação e seus documentos hospedados, e então executam um conversor em CI para soltar uma referência Markdown no repositório para leitura offline. A especificação permanece canônica; o Markdown é um artefato derivado que você pode regenerar a qualquer momento.

Conclusão

Converter OpenAPI para Markdown é um problema resolvido, desde que você trate a especificação como a fonte e o Markdown como um arquivo derivado. Para uma referência rápida de repositório, um conversor de uma linha como openapi-to-md cumpre a tarefa. Para um site de documentação tematizável, Widdershins oferece templates e abas de código. Para um layout interno exato, um script curto sobre a especificação analisada vence. E quando você quer que a especificação, os documentos renderizados e os testes que os mantêm sincronizados vivam juntos, importar para o Apidog remove a desatualização que quebra todas as outras abordagens ao longo do tempo.

Seja qual for a sua escolha, automatize-a. Gere o Markdown em CI a cada mudança na especificação, e os documentos que sua equipe lê sempre corresponderão à API que eles descrevem.