Ejemplo de OpenAPI

Esta página muestra un endpoint en vivo generado a partir de una especificación OpenAPI. El esquema de solicitud, los modelos de respuesta y los ejemplos de código del panel derecho se generan automáticamente a partir de la spec, sin necesidad de redacción manual.

Qué se genera

A partir de una sola línea de frontmatter openapi, Jamdesk genera automáticamente:

• Una insignia de endpoint que muestra el método y la ruta con codificación por colores
• Documentación de parámetros para los parámetros de ruta, consulta, encabezado y cuerpo
• Esquemas de solicitud y respuesta, incluidos los objetos anidados y los arrays
• Ejemplos de código en cURL, Python, JavaScript, Go, Ruby, C#, Java, Rust y PHP (configurable mediante api.examples.languages)
• Detalles de autenticación extraídos de los esquemas de seguridad de la spec

Todas las referencias $ref de tu spec se resuelven automáticamente, por lo que puedes organizar los esquemas con components/schemas como de costumbre.

Las descripciones de tu spec se renderizan como Markdown, no como texto sin formato: las descripciones de operación, parámetro, cuerpo de solicitud, respuesta y esquema admiten el mismo negrita, code, listas, enlaces y tablas GFM que usarías en una página .mdx.

Configurar OpenAPI

Coloca tu spec de OpenAPI 3.x (YAML o JSON) en el directorio openapi/, regístrala en docs.json bajo api.openapi y luego añade openapi: /openapi/your-spec.yaml METHOD /path al frontmatter de cualquier página. Consulta la guía de configuración de OpenAPI para más detalles.

Generar una página para cada operación

En lugar de crear una página por endpoint, apunta una pestaña de navegación a la spec y deja que Jamdesk construya toda la referencia:

{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": { "source": "/openapi/api.yaml", "generate": true }
      }
    ]
  }
}

Cada operación obtiene una página y la barra lateral se agrupa por tag. Los archivos .mdx ya incluidos en el repositorio tienen prioridad en caso de colisión de slug, por lo que puedes adoptar este enfoque una página a la vez, y cambiar el nombre de una ruta en tu spec redirige la URL antigua en lugar de romperla. Consulta navigation openapi para conocer todas las reglas y los límites actuales.

Páginas relacionadas