Cómo convertir especificaciones OpenAPI a documentos Markdown limpios automáticamente

Su archivo OpenAPI es la fuente de verdad de su API. Enumera cada ruta, cada parámetro, cada forma de respuesta. El problema es que casi nadie en su equipo quiere leer YAML o JSON en bruto. Un ingeniero de backend quiere una referencia rápida de los puntos finales en el repositorio. Un desarrollador frontend quiere una tabla de campos de solicitud que pueda escanear en una solicitud de extracción. Un redactor técnico quiere algo que pueda pegar en una wiki sin volver a escribir todo el esquema.

Markdown es el formato que se adapta a todos esos lectores. Se renderiza en GitHub, en Confluence, en un generador de sitios estáticos y en un editor de texto sin formato. Por lo tanto, la tarea recurrente es la siguiente: tomar un archivo openapi.yaml que ya existe y convertirlo en un Markdown limpio que los humanos realmente abran. Hacerlo a mano es lento y se desvía en el momento en que alguien añade un punto final. Hacerlo automáticamente es la única versión que sobrevive al contacto con un ciclo de lanzamiento real.

Por qué generar Markdown desde OpenAPI

Un documento OpenAPI está diseñado para máquinas. Las herramientas lo analizan para generar clientes, ejecutar pruebas de contrato, validar solicitudes y renderizar documentos interactivos. Esa legibilidad por máquina es el objetivo principal, y vale la pena protegerla. Si desea un repaso sobre cómo mantener la especificación correcta, la guía de herramientas de validación de OpenAPI cubre el linting antes de generar cualquier cosa a partir de ella.

Markdown resuelve un problema diferente: la distribución a humanos en lugares que no ejecutan un renderizador de OpenAPI. Algunos casos concretos surgen una y otra vez.

• Una carpeta README.md o /docs en el repositorio, para que un nuevo colaborador vea la lista de puntos finales sin salir de la base de código.
• Una descripción de la solicitud de extracción que necesita mostrar lo que un nuevo punto final acepta y devuelve.
• Una página de Confluence o Notion donde el equipo en general, incluidos los no ingenieros, revisa el contrato.
• Un sitio de documentación estático construido con Docusaurus, MkDocs o Hugo, todos los cuales aceptan Markdown como entrada.

La palabra clave es automáticamente. Un archivo Markdown que escribes una vez y olvidas es incorrecto en el siguiente sprint. Un archivo Markdown regenerado a partir de la especificación en cada cambio se mantiene fiel al contrato de forma gratuita. Esa es la diferencia entre documentos en los que la gente confía y documentos que la gente aprende a ignorar.

Los métodos de conversión, de rápidos a infalibles

No existe un comando oficial único que se envíe con OpenAPI para producir Markdown. En su lugar, existe un pequeño ecosistema de convertidores, además de los motores de documentación integrados en las plataformas API. Aquí está el panorama, ordenado aproximadamente por la cantidad de configuración que requiere cada uno.

Elija según la cantidad de control que necesite y dónde debe aterrizar la salida. Las siguientes secciones muestran cada uno en funcionamiento.

Método 1: un convertidor de código abierto de una línea

La ruta más rápida es un convertidor dedicado. Dos conocidos cubren los mundos de Node y Python.

Para un proyecto Node, openapi-to-md toma un documento v2 o v3 en YAML o JSON y escribe un archivo Markdown estructurado. Puede ejecutarlo sin una instalación global:

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

Para una cadena de herramientas Python, openapi-markdown hace el mismo trabajo con una instalación de pip y un solo comando:

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

Ambos leen la especificación, recorren cada ruta y esquema, y emiten un archivo Markdown con encabezados por punto final y tablas para parámetros y respuestas. El argumento del archivo de salida es opcional en algunas de estas herramientas; si lo omite, se establece de forma predeterminada en el nombre de entrada con una extensión .md. Eso es suficiente para una referencia de repositorio que se regenera bajo demanda.

La desventaja de los convertidores rápidos es el control del diseño. Obtienes su estructura, no la tuya. Si sus tablas predeterminadas coinciden con la forma en que su equipo lee los documentos, ha terminado en una línea. Si necesita ejemplos de código en cinco idiomas o un orden de sección específico, querrá el siguiente método.

Método 2: Widdershins para documentos con temas y ejemplos de código

Widdershins es la herramienta Node establecida para convertir un archivo OpenAPI o Swagger en Markdown compatible con Slate. Es la que debe usar cuando desea pestañas de código de idioma y una plantilla personalizable, y cuando el Markdown alimenta un generador de sitios estáticos como Docusaurus o MkDocs.

Instálelo y ejecute la conversión básica:

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

Agregue idiomas de ejemplo de código y elimine el encabezado inicial cuando esté canalizando la salida a algún lugar que agregue el suyo propio:

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

Widdershins utiliza un sistema de plantillas, por lo que puede anular el diseño de cualquier sección en lugar de aceptar el predeterminado. Eso lo convierte en el puente entre un volcado en bruto y un sitio de documentos completamente hecho a mano. El costo es que ahora es dueño de una plantilla y un paso de compilación, lo que está bien para un repositorio de documentación y es excesivo para un README rápido.

Método 3: un script personalizado cuando necesita un diseño exacto

A veces, ninguno de los convertidores listos para usar produce la forma que desea. Quizás necesite un archivo Markdown por etiqueta, o un índice de puntos finales compacto, o tablas de esquema que coincidan con una guía de estilo interna. En ese caso, analice la especificación usted mismo y cree una plantilla para la salida. La especificación es solo datos estructurados, por lo que esto es menos trabajo de lo que parece.

Una versión mínima de Node que enumera cada operación se ve así:

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("| Nombre | En | Requerido | Descripción |");
      lines.push("| ---- | -- | -------- | ----------- |");
      for (const p of params) {
        lines.push(`| ${p.name} | ${p.in} | ${p.required ? "sí" : "no"} | ${p.description ?? ""} |`);
      }
      lines.push("");
    }
  }
}

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

Eso es alrededor de cuarenta líneas para un control total sobre la salida. Usted decide los encabezados, las columnas de la tabla, la división del archivo. La desventaja es el mantenimiento: cuando la versión de OpenAPI a la que se dirige agrega una función, su script tiene que aprenderla. Para un estilo interno estable, ese intercambio suele valer la pena. Para una amplia cobertura de especificaciones, confíe en un convertidor mantenido en su lugar. Si está sopesando si script esto o comprarlo, el resumen de generadores de documentación de API con exportación de Markdown compara las opciones mantenidas una al lado de la otra.

Método 4: mantenga la especificación, los documentos y las pruebas juntos en Apidog

Todos los convertidores anteriores comparten un punto ciego. Convierten una especificación en Markdown, y luego los dos se desvían. Alguien edita la API, olvida volver a ejecutar el convertidor y el Markdown miente. La solución es dejar de tratar la especificación como un archivo que vive solo y comenzar a tratarla como parte de un espacio de trabajo donde los documentos y las pruebas se actualizan con ella.

Ese es el modelo que utiliza Apidog. Importa su archivo openapi.yaml existente, y Apidog lee cada ruta, esquema y ejemplo en un proyecto. A partir de ahí, obtiene documentación de API alojada y renderizada generada directamente a partir de la especificación importada, sin un paso de compilación separado. El flujo de importación completo se cubre en cómo importar Swagger u OpenAPI y generar solicitudes, y la ruta desde la especificación hasta la referencia publicada en generación automática de documentación de API a partir de OpenAPI.

Dos cosas hacen que esto sea diferente de un convertidor de un solo uso.

Primero, la documentación admite bloques de contenido Markdown propios. La referencia de punto final generada proviene de la especificación, y usted superpone Markdown escrito a mano a su alrededor: una página de introducción, notas de autenticación, entradas de registro de cambios. Los consejos para crear documentación con Markdown de Apidog explican ese lado de la autoría. Por lo tanto, no está eligiendo entre documentos generados y escritos; obtiene ambos en un solo lugar.

En segundo lugar, la misma especificación importada se convierte en la base para escenarios de prueba. Construye solicitudes y aserciones contra los puntos finales que define la especificación, luego las ejecuta para probar que la API en vivo aún coincide con el contrato que produjo sus documentos. Eso cierra el ciclo de deriva: si la API cambia y rompe el contrato, las pruebas fallan y usted sabe que los documentos están obsoletos antes de que un lector lo sepa.

Para seguir adelante, descargue Apidog, importe una especificación y abra los documentos generados en el mismo proyecto. El punto no es que Apidog imprima un archivo .md en el disco. Es que la especificación, los documentos legibles por humanos y las pruebas que los mantienen honestos dejan de ser tres archivos desconectados.

Hágalo automático: regenere Markdown en CI

Un convertidor que ejecuta a mano es un convertidor que olvida. Todo el valor de generar Markdown desde OpenAPI solo aparece cuando la generación se ejecuta por sí misma, en cada cambio. El patrón es simple: en cada push que toca la especificación, regenere el Markdown y vuelva a confirmarlo, o publíquelo.

Aquí hay un trabajo de GitHub Actions que regenera la referencia cada vez que cambia openapi.yaml:

name: Generar documentos de 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: Convertir especificación a Markdown
        run: npx openapi-to-md openapi.yaml docs/api-reference.md
      - name: Confirmar 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 referencia de API"
          git push

Ahora el Markdown nunca puede desviarse más de un commit de la especificación. La misma idea funciona en GitLab CI o en cualquier ejecutor con Node o Python; simplemente cambie el paso de conversión por widdershins o su script.

Hay una pieza más que vale la pena conectar. Los documentos regenerados solo son confiables si la especificación de la que provienen sigue siendo precisa. Ahí es donde una ejecución de prueba de línea de comandos se gana su lugar en la misma tubería. La CLI de Apidog ejecuta los escenarios de prueba que construyó contra su especificación importada, sin interfaz gráfica, con un solo comando:

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

Sale con un código de error distinto de cero si falla alguna aserción, lo que falla la compilación, lo que le impide publicar documentos que describan una API que ya no se comporta de esa manera. La superficie completa de los indicadores se encuentra en la referencia del comando apidog run, y la configuración de la tubería más amplia en la guía completa de Apidog CLI. Empareje la generación de documentos con una prueba de contrato y los dos se refuerzan mutuamente: la especificación produce los documentos, y la prueba demuestra la especificación.

Limpiar el Markdown generado

El Markdown generado rara vez es perfecto en la primera pasada. Algunos hábitos lo mantienen legible.

• Elimine el encabezado inicial generado automáticamente cuando el renderizador de destino no lo desee. Widdershins hace esto con --omitHeader; para otras herramientas, un sed rápido sobre la parte superior del archivo funciona.
• Decida una división de archivos. Un archivo Markdown gigante está bien para un README. Para un sitio de documentos, divida por etiqueta o recurso para que cada página sea corta.
• Mantenga los ejemplos reales. La mayoría de los convertidores extraen los valores de ejemplo directamente de la especificación, por lo que la calidad de sus documentos generados sigue la calidad de sus examples en OpenAPI. Mejores ejemplos, mejores documentos.
• Regenere, no edite a mano. En el momento en que edita a mano el Markdown generado, la siguiente conversión lo sobrescribe. Coloque el contenido escrito a mano en archivos separados y deje que el generador solo sea propietario de la sección de referencia.

Si su propia especificación es un desastre, corríjala en la fuente. Las especificaciones más limpias producen documentos más limpios, y la publicación de herramientas de validación de OpenAPI muestra cómo hacer linting para las lagunas que producen una salida fea.

Elegir el método adecuado para su equipo

Adapte la herramienta a dónde debe ir el Markdown y cuánto control necesita.

• Si desea una referencia de repositorio en un solo comando y no le importa mucho el diseño: use openapi-to-md o openapi-markdown.
• Si está creando un sitio de documentos con ejemplos de código y desea una plantilla con temas: use Widdershins.
• Si tiene una guía de estilo interna que los convertidores no pueden igualar: escriba un pequeño script sobre la especificación analizada.
• Si desea que los documentos, la especificación y las pruebas que los mantienen honestos estén juntos en un solo espacio de trabajo, con salida alojada y sin compilación separada que supervisar: importe la especificación a Apidog.

Estas opciones no son mutuamente excluyentes. Muchos equipos usan Apidog como fuente de verdad para la especificación y sus documentos alojados, luego ejecutan un convertidor en CI para colocar una referencia Markdown en el repositorio para lectura sin conexión. La especificación permanece canónica; el Markdown es un artefacto derivado que puede regenerar en cualquier momento.

En resumen

Convertir OpenAPI a Markdown es un problema resuelto siempre que trate la especificación como la fuente y el Markdown como un archivo derivado. Para una referencia rápida del repositorio, un convertidor de una línea como openapi-to-md hace el trabajo. Para un sitio de documentos con temas, Widdershins le ofrece plantillas y pestañas de código. Para un diseño interno exacto, un script corto sobre la especificación analizada es lo mejor. Y cuando desea que la especificación, los documentos renderizados y las pruebas que los mantienen sincronizados vivan juntos, la importación a Apidog elimina la deriva que rompe todos los demás enfoques con el tiempo.

Elija lo que elija, automatícelo. Genere el Markdown en CI en cada cambio de especificación, y los documentos que su equipo lee siempre coincidirán con la API que describen.