Documentação OpenAPI em Markdown

Documentação OpenAPI em Markdown

Cole um documento OpenAPI 3 ou Swagger 2 — em JSON ou YAML — e esta ferramenta transforma-o numa referência de API em Markdown que pode inserir diretamente num README, numa página wiki ou num site de documentação. Cada operação torna-se a sua própria secção, de modo que uma especificação que apenas uma máquina poderia ler confortavelmente se torna algo que um colega ou um novo integrador pode examinar.

O resultado inclui uma tabela de conteúdos que liga a cada grupo e endpoint, uma tabela de parâmetros (ou uma lista simples) para parâmetros de caminho, query, cabeçalho e cookie, uma amostra de corpo de pedido gerada, uma tabela de códigos de resposta com as suas descrições, e um corpo de resposta de exemplo do primeiro esquema correspondente. Agrupe endpoints por etiqueta ou pelo primeiro segmento do seu caminho, escolha se as amostras de pedido são apresentadas como um corpo JSON ou como um comando curl pronto a usar, e escolha o nível de profundidade dos cabeçalhos de endpoint para que o resultado se encaixe num documento existente. Um botão inclui ou omite endpoints descontinuados; outro despeja cada esquema sob componentes (ou as definições do Swagger) como a sua própria secção no final.

Os apontadores "$ref" dentro do mesmo ficheiro são seguidos para parâmetros, corpos de pedido e resposta, e esquemas, de modo que uma especificação que depende de componentes produz tabelas e amostras completas em vez de strings $ref nus. As referências para outro ficheiro ou um URL são deixadas em paz, pois nada aqui faz um pedido de rede. Se o Markdown gerado exceder o limite de saída da ferramenta, obtém uma mensagem clara em vez de um separador congelado.

Tudo corre localmente no seu navegador — a sua especificação de API, que frequentemente descreve sistemas que não quer expor, nunca é enviada para lado nenhum. Copie o Markdown, descarregue-o como ficheiro .txt ou envie-o para outra ferramenta para continuar a trabalhar nele.

FAQ