Saltar al contenido principal
Si actualmente estás usando páginas MDX individuales para tus endpoints de API, puedes migrar a la generación automática de páginas a partir de tu especificación de OpenAPI, sin perder la posibilidad de personalizar cada página. Esto puede ayudarte a reducir la cantidad de archivos que necesitas mantener y a mejorar la coherencia de la documentación de tu API. Puedes definir metadata y contenido para cada endpoint en tu especificación de OpenAPI y organizar los endpoints donde quieras dentro de tu navegación.

​
Pasos de migración

1

Prepara tu especificación de OpenAPI.

Asegúrate de que tu especificación de OpenAPI sea válida e incluya todos los endpoints que quieras documentar.Para cualquier endpoint en el que quieras personalizar los metadatos o el contenido, agrega la extensión x-mint al endpoint. Consulta la extensión x-mint para más detalles.Para cualquier endpoint que quieras excluir de tu documentación, agrega la extensión x-hidden al endpoint.
Valida tu archivo OpenAPI usando el Swagger Editor o la CLI de Mint.
2

Actualiza tu estructura de navegación.

Reemplaza las referencias a páginas MDX con endpoints de OpenAPI en tu docs.json.
"navigation": {
  "groups": [
    {
      "group": "API Reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "overview",
        "authentication",
        "introduction",
        "GET /health",
        "quickstart", 
        "POST /users",
        "GET /users/{id}",
        "advanced-features"
      ]
    }
  ]
}
3

Elimina los archivos MDX antiguos.

Después de verificar que tu nueva navegación funciona correctamente, elimina los archivos MDX de endpoints que ya no necesites.
Puedes personalizar cómo se muestra la documentación de tu API en tu navigation.
Combina páginas de API generadas automáticamente con otras páginas: 
"navigation": {
  "groups": [
    {
      "group": "Referencia de API",
      "openapi": "openapi.json",
      "pages": [
        "api/overview",
        "GET /users",
        "POST /users", 
        "api/authentication"
      ]
    }
  ]
}

​
Varias versiones de la API

Organiza distintas versiones de la API usando pestañas o groups: 
"navigation": {
  "tabs": [
    {
      "tab": "API v1",
      "openapi": "specs/v1.json"
    },
    {
      "tab": "API v2", 
      "openapi": "specs/v2.json"
    }
  ]
}

​
Cuándo usar páginas MDX individuales

Considera mantener páginas MDX individuales cuando necesites:
  • Contenido personalizado extenso por endpoint, como componentes de React o ejemplos largos.
  • Diseños de página únicos.
  • Enfoques de documentación experimentales para endpoints específicos.
Para la mayoría de los casos de uso, la navigation de OpenAPI ofrece una mejor mantenibilidad y coherencia.