Ferramentas CLI Gratuitas e Open Source para Documentação de API

Ao escolher uma ferramenta para gerar a documentação da sua API, a licença faz parte da decisão. Um gerador de código aberto significa que você pode ler o código, hospedar a saída por conta própria (self-host), fazer um fork se ele parar de ser atualizado, e nunca encontrar um limite de licenças ou um paywall em um recurso que você já implementou. Para uma tarefa que roda em cada build de CI, isso é tão importante quanto a qualidade da saída.

Esta lista é a seleção de ferramentas de documentação de API de código aberto que funcionam a partir da linha de comando. Cada ferramenta aqui tem seu código-fonte disponível sob uma licença real, MIT ou Apache 2.0, hospedada no GitHub, e é gratuita para usar sem necessidade de conta. Você a aponta para um arquivo OpenAPI ou Swagger e ela te entrega Markdown, uma página HTML estática, ou um site de documentação completo que você possui e hospeda por conta própria.

Vou sinalizar a licença exata e a capacidade de auto-hospedagem para cada uma, porque essa é a principal razão pela qual você está lendo um resumo de código aberto em vez de um geral. Se você deseja um panorama mais amplo, o resumo das melhores ferramentas de documentação de API REST também aborda as plataformas com interface gráfica. A Especificação OpenAPI é o formato que todas as ferramentas abaixo leem, então uma especificação válida é seu ponto de partida.

Uma observação honesta logo de cara. Apidog aparece perto do final, e não é uma opção de código aberto; é uma plataforma freemium comercial. Eu a incluí apenas como uma observação destacada para o caso em que as ferramentas abertas deixam uma lacuna, e serei explícito sobre essa distinção.

O que torna uma ferramenta de documentação CLI “de código aberto”

Código aberto não é apenas “gratuito para baixar”. Para ferramentas de documentação que você conectará a um build, três coisas decidem se uma ferramenta é verdadeiramente sua.

Uma licença real. MIT ou Apache 2.0 significa que você pode usar, modificar e redistribuir a ferramenta comercialmente sem pedir permissão. Ambas são aprovadas pela OSI. Apache 2.0 adiciona uma concessão explícita de patente, que algumas equipes jurídicas preferem. Todas as ferramentas abaixo possuem uma das duas.

Saída auto-hospedável. O objetivo da documentação aberta é que nada dependa dos servidores de um fornecedor. Essas ferramentas escrevem arquivos estáticos: Markdown que você commit, uma única página HTML, ou uma pasta de HTML/CSS/JS. Você a hospeda no GitHub Pages, S3, ou um servidor Nginx simples, e ela continua funcionando independentemente do projeto por trás da ferramenta.

Manutenção e comunidade. O código-fonte disponível só ajuda se o código estiver ativo. Estrelas, commits recentes e issues abertas indicam se um fork seria viável caso você precise. Algumas ferramentas aqui estão arquivadas, mas ainda funcionam; vou avisar quando for o caso.

Para o ângulo de custo zero em opções abertas e freemium, a lista de ferramentas gratuitas de documentação de API é o artigo complementar. Agora, as ferramentas.

Redocly CLI

Redocly CLI é a maneira mais rápida de transformar uma especificação em uma referência HTML polida e autocontida. É licenciado sob MIT e tem um "core" aberto: a CLI e o motor de renderização Redoc subjacente são de código aberto no GitHub, enquanto alguns recursos de portal hospedado estão no produto pago da Redocly. O comando build-docs está totalmente na parte de código aberto.

npx @redocly/cli build-docs openapi.yaml -o api-docs.html

Isso escreve um arquivo HTML construído no Redoc. Abra-o localmente, coloque-o em qualquer host estático ou anexe-o a um lançamento. Nada se conecta a servidores externos, e você pode executá-lo offline assim que o pacote estiver em cache.

Melhor para: uma referência de API de página única limpa a partir de um comando, licenciada sob MIT e auto-hospedada. Limitações honestas: a saída é uma única página, então é uma referência em vez de um portal de várias páginas, e os temas mais ricos estão na camada paga. Se você está comparando os motores de renderização, a comparação de alternativas ao Redocly descreve onde a linha de código aberto se encontra.

Widdershins

Widdershins é um conversor puro sob a licença MIT. Ele lê OpenAPI 3, Swagger 2 ou AsyncAPI e gera Markdown; esse é o trabalho completo. Como a saída é Markdown simples, você a possui completamente: commite-a, compare-a em um pull request, ou alimente-a em qualquer site estático que você já executa.

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

O Markdown que ele escreve é compatível com Slate, o que o combina perfeitamente com os geradores de site mais adiante nesta lista. Flags úteis: --omitHeader remove o cabeçalho e --language_tabs escolhe os idiomas dos exemplos de código.

Melhor para: transformar conteúdo de especificação em Markdown versionável com zero dependência. Limitações honestas: Markdown é tudo o que você obtém. Não há estilização nem site renderizado, então Widdershins é uma parte de um pipeline; outra coisa transforma o Markdown em páginas.

OpenAPI Generator

OpenAPI Generator é licenciado sob Apache 2.0 e mantido pela comunidade, sendo um fork do Swagger Codegen em 2018. É mais conhecido por seus SDKs de cliente, mas também inclui geradores de documentação: o gerador markdown escreve uma pasta de Markdown, e html2 escreve uma única página HTML autocontida.

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/

A licença Apache 2.0 e sua concessão de patente facilitam a aprovação por equipes jurídicas cautelosas, e o projeto é um dos mais ativamente mantidos neste espaço.

Melhor para: reutilizar uma ferramenta para SDKs e documentação, sob uma licença permissiva com forte apoio da comunidade. Limitações honestas: o wrapper npm ainda baixa um jar Java na primeira execução, então não é um binário único, e a saída gerada por template é simples. Se você precisa apenas de documentação, existem conversores mais leves.

Swagger Codegen

Swagger Codegen é o gerador original baseado em templates da equipe Swagger, licenciado sob Apache 2.0. Ele antecede o fork do OpenAPI Generator e ainda é mantido pela SmartBear. Para documentação, ele oferece dois caminhos: html para uma referência estática de página única e dynamic-html para um pequeno site interativo.

npm install -g swagger-codegen-cli
swagger-codegen-cli generate -i openapi.yaml -l html -o docs/

Os dois projetos compartilham DNA e muitas opções, então se sua equipe já padronizou na cadeia de ferramentas Swagger, isso o mantém dentro dela.

Melhor para: equipes já investidas no ecossistema Swagger que desejam documentação da mesma ferramenta Apache 2.0 que gera seus stubs. Limitações honestas: é baseado em Java como o OpenAPI Generator, e o desenvolvimento é mais lento do que o fork da comunidade. Para a maioria das novas configurações, o OpenAPI Generator é a escolha mais ativa; Swagger Codegen ganha em continuidade.

Docusaurus com o plugin OpenAPI

Se uma única página HTML não for suficiente e você quiser um site de documentação real e versionado, Docusaurus é a âncora de código aberto. É licenciado sob MIT, construído pelo Meta, e um dos geradores de site estático mais amplamente utilizados na web. Por si só, ele renderiza Markdown e MDX; o plugin docusaurus-openapi-docs, também MIT e mantido pela Palo Alto Networks, adiciona a geração de especificação para documentação.

npx create-docusaurus@latest my-docs classic
npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
npm run docusaurus gen-api-docs all

Após configurar o plugin com o caminho da sua especificação, gen-api-docs converte o arquivo OpenAPI em páginas MDX que são renderizadas dentro do site Docusaurus, completas com um painel “experimentar” e navegação na barra lateral.

Melhor para: um portal de documentação completo e auto-hospedado com versionamento, pesquisa e guias escritos à mão ao lado da referência gerada. Limitações honestas: é a configuração mais pesada aqui. Você está montando um site React e uma etapa de build, então é excessivo se tudo o que você precisa é de uma página de referência. Para isso, o Redocly CLI é o caminho mais curto.

Slate

Slate é o layout clássico de documentação de API em três colunas: navegação à esquerda, prosa no meio, exemplos de código à direita, tudo renderizado como um site estático. É licenciado sob Apache 2.0 e alimentado por Middleman, então requer uma toolchain Ruby. Diferente dos conversores acima, Slate não lê OpenAPI diretamente; você escreve Markdown, e Slate o renderiza.

# after cloning your Slate fork and running bundle install
bundle exec middleman build

Isso escreve um site estático completo em uma pasta build/ que você pode hospedar em qualquer lugar. É aqui que Widdershins se mostra útil: converta sua especificação para Markdown e, em seguida, deixe o Slate renderizá-la naquele layout reconhecível.

Melhor para: documentação narrativa e curada manualmente, onde você deseja controle editorial sobre a estrutura e a prosa, em um site estático totalmente auto-hospedado. Limitações honestas: o repositório original está arquivado (o mantenedor se afastou), embora ainda funcione e os forks estejam ativos, e a dependência de Ruby é mais pesada do que um comando npx de uma linha. Se sua documentação é regenerada diretamente de uma especificação, um conversor é mais leve.

Apidog CLI (observação honesta, não é uma entrada de código aberto)

As ferramentas acima são todas de código aberto, e cada uma cobre uma fatia: converter, renderizar ou hospedar um arquivo estático. A lacuna que elas deixam é um projeto ativo. Se sua API não é um arquivo YAML solitário, mas um projeto mantido com endpoints, schemas e exemplos, você acaba encadeando um conversor, um renderizador e um host manualmente e mantendo os três em sincronia.

Essa é a lacuna que o binário apidog-cli preenche. Para ser direto sobre a licença: Apidog não é de código aberto. É uma plataforma freemium comercial com uma camada gratuita, e a CLI se comunica com um projeto hospedado em vez de uma especificação local. Eu a incluí aqui apenas para que a comparação seja honesta sobre o que as ferramentas abertas cobrem e não cobrem, e não como uma opção de código aberto.

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html

Uma única exportação transforma o projeto em Markdown ou HTML sem pipeline de build, e apidog doc e apidog docs-site gerenciam recursos de documentação a partir de um script. A saída é JSON estruturado, então ela se integra perfeitamente em CI ou em um agente. O guia completo do Apidog CLI detalha a autenticação e cada grupo de comandos. Se o fluxo de trabalho de exportação para Markdown é o que você procura, o artigo gerador de documentação de API com exportação para Markdown aprofunda-se no assunto.

Onde está a distinção: as ferramentas de código aberto oferecem código que você possui, arquivos que você auto-hospeda e nenhuma dependência de fornecedor. O Apidog oferece uma rota integrada de um projeto mantido para documentos compartilháveis, ao custo de ser um produto freemium hospedado. Escolha com base se sua fonte de verdade é uma especificação estática ou um projeto ativo.

Como escolher

Combine a licença e a saída com o que sua equipe precisa possuir.

A versão resumida: para uma especificação básica e uma referência HTML compartilhável, use Redocly CLI. Para Markdown que você versiona, Widdershins. Se você já está gerando SDKs, o OpenAPI Generator também faz documentação, e o Swagger Codegen te cobre se você está padronizado no Swagger. Quando você quer um portal real com versionamento e guias, Docusaurus mais o plugin OpenAPI é a âncora de código aberto, e Slate é a escolha para documentação escrita à mão e editorialmente controlada. Cada uma dessas ferramentas tem o código-fonte disponível e pode ser auto-hospedada, então nada que você implementa depende de um fornecedor continuar no mercado. Para uma visão mais ampla das opções sem custo, o resumo de ferramentas gratuitas de documentação de API reúne opções abertas e freemium.

Conclusão

A escolha de uma CLI de documentação de código aberto se resume a licença, saída e onde sua documentação reside. MIT e Apache 2.0 permitem que você use, modifique e auto-hospede sem custo de licença, então escolha a ferramenta mais leve que produza a saída que você precisa: Redocly CLI para uma página, Widdershins para Markdown, OpenAPI Generator ou Swagger Codegen para documentação ao lado de seus SDKs, Docusaurus para um portal, Slate para páginas curadas manualmente.

Se sua API reside em um projeto mantido em vez de um arquivo avulso, e você prefere exportar documentação a encadear três ferramentas, Baixe o Apidog e experimente apidog export contra um projeto. Ele se encaixa em um trabalho de CI para que sua documentação seja reconstruída toda vez que a API mudar, apenas tenha clareza de que é uma plataforma freemium, não um binário de código aberto.