Você tem um arquivo OpenAPI e quer documentação a partir dele. Você não quer configurar um serviço, fazer login em um portal ou adicionar uma etapa de build que traga metade do npm. Você quer um único comando que leia a especificação e entregue um arquivo Markdown ou uma única página HTML que você possa hospedar em qualquer lugar.
É para isso que serve esta lista. Cada ferramenta aqui é pequena: um único binário, um comando `npx` de uma linha ou um pacote que você instala uma vez e esquece. Elas iniciam rapidamente, precisam de pouca ou nenhuma configuração, e realizam o trabalho de documentação sem arrastar uma plataforma completa. Algumas emitem Markdown que você insere em um site de documentação existente. Algumas emitem um arquivo HTML autônomo. Todas elas rodam em CI e em um terminal, o que é o objetivo.
Se você deseja o campo mais amplo das plataformas de documentação, o resumo das melhores ferramentas de documentação de API REST cobre o lado mais pesado em GUI. Esta peça é o recorte com foco no terminal e baixa pegada. Para a referência oficial sobre o que um gerador de documentação lê, a Especificação OpenAPI é a fonte de verdade que cada ferramenta abaixo analisa.
O que torna uma ferramenta CLI "leve" para documentação de API
Ser leve não significa ser fraco. É sobre pegada e atrito. Quatro coisas o definem.
Tamanho da instalação e dependências. Um binário ou um pacote npm supera um framework. Se gerar uma página de documentação significa instalar um tempo de execução de linguagem, mais um bundler, mais um sistema de plugins, isso não é leve, não importa a aparência da saída.
Inicialização e configuração. As melhores ferramentas leem sua especificação e produzem saída com configuração zero. Você aponta o comando para `openapi.yaml` e recebe um arquivo de volta. Qualquer coisa que precise de um arquivo de configuração para rodar perde pontos aqui.
Saída de propósito único. Cada ferramenta abaixo faz uma coisa: especificação de entrada, documentação de saída. Markdown ou HTML, nada mais anexado. É isso que as mantém rápidas e previsíveis em um pipeline.
Executa em qualquer lugar. Sem GUI, sem login para as ferramentas abertas, sem servidor para manter ativo. Funciona no seu laptop e funciona da mesma forma em um job de CI. Para um conjunto mais amplo de opções gratuitas, a lista de ferramentas de documentação de API gratuitas tem as plataformas; esta é a fatia CLI disso.
Agora as ferramentas, da menor para a maior.
Widdershins
Widdershins é o mais compacto possível. É um único pacote npm que converte um arquivo OpenAPI 3, Swagger 2 ou AsyncAPI em Markdown. Esse é todo o trabalho. Ele não renderiza um site nem executa um servidor; ele entrega um arquivo `.md` e sai do caminho.
npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
O Markdown que ele produz é compatível com Slate, o que é importante se você planeja alimentá-lo em um site estático mais tarde. Flags úteis: `--omitHeader` remove o front-matter YAML, e `--language_tabs` controla quais linguagens de exemplo de código aparecem.
Melhor para: obter conteúdo de especificação em Markdown que você pode commitar, comparar e inserir em qualquer sistema de documentação. Limites honestos: Markdown é tudo o que você obtém. Não há estilização, nenhum painel interativo de "experimente" e nenhuma saída hospedada. Widdershins é um conversor, não um renderizador, então você o emparelha com algo que transforma Markdown em um site.
OpenAPI Generator (geradores de documentação)
O OpenAPI Generator é mais conhecido por seus SDKs de cliente, mas também inclui geradores de documentação, e eles são úteis quando uma especificação é tudo o que você tem. O gerador `markdown` escreve uma pasta de Markdown; o gerador `html2` escreve uma única página HTML autocontida. Você pode executá-lo através do wrapper npm sem instalar o Java por conta própria.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/
O wrapper npm ainda baixa um jar suportado por JDK nos bastidores, então é mais pesado que o Widdershins na primeira execução. Depois disso, é uma geração de um único comando.
Melhor para: reutilizar uma ferramenta que você já pode executar para SDKs para também emitir documentação, com uma escolha entre Markdown e HTML autônomo. Limites honestos: a saída é simples e baseada em modelos, e a primeira invocação baixa um jar, então não é verdadeiramente um binário único. Se você precisa apenas de documentação e nada mais, existem opções mais leves.
Redocly CLI (build-docs)
Se você deseja uma página HTML autônoma e de boa aparência a partir de um único comando, o Redocly CLI é o caminho mais curto. O comando `build-docs` empacota sua especificação em um único arquivo HTML autocontido construído sobre o Redoc. Sem servidor, sem build de hospedagem separado; você obtém um arquivo que pode abrir, enviar por e-mail ou colocar em qualquer host estático.
npx @redocly/cli build-docs openapi.yaml
Por padrão, ele escreve `redoc-static.html`. Altere o nome com `--output`:
npx @redocly/cli build-docs openapi.yaml --output api.html
Como ele roda via `npx`, você nem precisa instalá-lo globalmente para experimentá-lo. Melhor para: uma referência de página única polida a partir de um comando, com um tema padrão limpo e sem a necessidade de gerenciar hospedagem. Limites honestos: a saída é um único arquivo HTML, então é uma página de referência em vez de um portal de documentação multi-página, e os temas mais ricos e pré-visualizações estão nas camadas pagas do Redocly. Se você estiver comparando-o com renderizadores semelhantes, as comparações de alternativas ao Redocly e alternativas ao Scalar apresentam as compensações.
Slate
Slate é a exceção aqui: não é um conversor de especificação para documentação, é um gerador de site estático para documentação de API escrita à mão. Você escreve Markdown, e o Slate constrói o clássico layout de documentação de três colunas (navegação, conteúdo e exemplos de código lado a lado) em um site estático autocontido. Ele é alimentado por Middleman, então precisa de Ruby.
# after cloning the slate repo and installing dependencies
bundle exec middleman build
Isso escreve um site estático completo para uma pasta `build/` que você pode hospedar em qualquer lugar. É aqui que Widdershins compensa: gere Markdown da sua especificação, então deixe o Slate renderizá-lo, e você obtém conteúdo baseado em especificação no layout do Slate.
Melhor para: documentação de API narrativa, curada manualmente, onde você deseja controle editorial sobre a estrutura e a prosa. Limites honestos: é a opção mais pesada nesta lista porque precisa de uma toolchain Ruby, e não lê OpenAPI por si só; você o alimenta com Markdown. Se sua documentação é gerada diretamente de uma especificação e raramente é editada manualmente, um conversor sozinho é mais leve.
Apidog CLI (export + doc)
As ferramentas abertas acima cobrem cada uma uma fatia: converter, renderizar ou hospedar. Se sua API já existe em um projeto em vez de um arquivo YAML isolado, juntá-las é o atrito. É aí que o binário `apidog-cli` se encaixa. É o companheiro de linha de comando para o Apidog, e uma exportação transforma um projeto em Markdown ou HTML sem um pipeline de build.
Instale-o via npm e autentique-se com um token:
npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
Em seguida, exporte a documentação do projeto para Markdown ou HTML em um único comando:
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html
A CLI também gerencia recursos de documentação diretamente. `apidog doc` lida com os documentos Markdown do projeto, e `apidog docs-site` gerencia sites de documentação publicados, para que você possa listar, criar e atualizar documentos a partir de um script ou job de CI:
apidog doc list --project <projectId>
apidog docs-site list --project <projectId>
A saída é JSON estruturado, o que facilita a canalização para outras etapas ou a entrega a um agente. Para a superfície completa de comandos, o guia completo do Apidog CLI detalha autenticação, projetos e cada grupo de comandos.
Aqui está o enquadramento honesto. O Apidog não é de código aberto, nem é um binário de propósito único; é uma plataforma freemium, e a CLI se comunica com um projeto hospedado. Ele também não faz lint do seu OpenAPI nem impõe um guia de estilo; Redocly e Spectral fazem isso. O que a CLI oferece é uma rota integrada de um projeto de API mantido para Markdown ou HTML compartilhável, em vez de encadear um conversor, um renderizador e um host manualmente. Se você deseja especificamente o caminho de exportação para Markdown, a peça gerador de documentação de API com exportação Markdown aprofunda-se nesse fluxo de trabalho.
Como escolher
Combine a ferramenta com o formato da sua entrada e a saída que você precisa.
| Ferramenta | Melhor para | Instalação | Código aberto? | Saída |
|---|---|---|---|---|
| Widdershins | Especificação para Markdown, rápido | npm i -g widdershins |
Sim (MIT) | Markdown |
| OpenAPI Generator | Documentação junto com SDKs | npm i -g @openapitools/openapi-generator-cli |
Sim (Apache 2.0) | Markdown ou HTML |
| Redocly CLI | Uma página HTML polida | npx @redocly/cli |
Sim (MIT, open core) | HTML Autônomo |
| Slate | Site de documentação curado manualmente | Ruby + Bundler | Sim (Apache 2.0) | Site estático |
| Apidog CLI | Exportar de um projeto ativo | npm i -g apidog-cli |
Não (camada gratuita) | Markdown ou HTML |
Em resumo: se você tem uma especificação pura e quer Markdown para commitar, use Widdershins. Se você quer uma página HTML compartilhável, `redocly build-docs` é o mais rápido. Se você está escrevendo documentação manualmente e quer um layout adequado, use Slate. E se sua API já existe em um projeto e você quer exportação mais gerenciamento de documentos em uma única CLI, use Apidog. Para uma visão geral sem custo, o resumo das ferramentas gratuitas de documentação de API reúne tudo isso.
Conclusão
Ferramentas de documentação leves se resumem a uma regra: escolha a menor coisa que produz a saída que você precisa. Widdershins e `redocly build-docs` cobrem a maioria dos casos de especificação para documentação em um único comando. O OpenAPI Generator vale a pena quando você já está gerando SDKs. O Slate justifica sua pegada mais pesada apenas quando você está escrevendo documentação manualmente. E quando sua API vive em um projeto real em vez de um arquivo solto, o export `apidog-cli` oferece Markdown ou HTML sem um pipeline.
Se esse último caso é o seu, Baixe o Apidog e experimente `apidog export` em um projeto; ele se encaixa perfeitamente em um job de CI para que sua documentação seja reconstruída sempre que a API mudar.