Documentación OpenAPI a Markdown
Convierte un documento OpenAPI o Swagger en documentación de referencia legible en Markdown.
Documentación OpenAPI a Markdown
Pega un documento OpenAPI 3 o Swagger 2 — en JSON o YAML — y esta herramienta lo convierte en una referencia de API en Markdown que puedes insertar directamente en un README, una página wiki o un sitio de documentación. Cada operación se convierte en su propia sección, por lo que una especificación que solo una máquina podría leer cómodamente se transforma en algo que un compañero o un nuevo integrador puede revisar rápidamente.
La salida incluye una tabla de contenidos con enlaces a cada grupo y punto final, una tabla de parámetros (o una lista simple) para parámetros de ruta, consulta, encabezado y cookie, un ejemplo de cuerpo de solicitud generado, una tabla de códigos de respuesta con sus descripciones, y un cuerpo de respuesta de ejemplo del primer esquema coincidente. Agrupa los puntos finales por etiqueta o por su primer segmento de ruta, elige si los ejemplos de solicitud se representan como un cuerpo JSON o un comando curl listo para usar, y selecciona qué tan profundos son los encabezados del punto final para que el resultado se anide dentro de un documento existente. Un interruptor incluye o excluye puntos finales obsoletos; otro vuelca cada esquema bajo componentes (o las definiciones de Swagger) como su propia sección al final.
Los punteros "$ref" dentro del mismo archivo se siguen para parámetros, cuerpos de solicitud y respuesta, y esquemas, por lo que una especificación que depende de componentes sigue produciendo tablas y ejemplos completos en lugar de cadenas $ref simples. Las referencias a otro archivo o una URL se dejan intactas, ya que nada aquí realiza una solicitud de red. Si el Markdown generado excede el límite de salida de la herramienta, obtienes un mensaje claro en lugar de una pestaña congelada.
Todo se ejecuta localmente en tu navegador — tu especificación de API, que a menudo describe sistemas que no quieres exponer, nunca se carga en ningún lugar. Copia el Markdown, descárgalo como archivo .txt o envíalo a otra herramienta para seguir trabajando en él.