Si actualmente usas páginas individuales en MDX para tus endpoints de API, puedes migrar a generar páginas automáticamente desde tu especificación de OpenAPI manteniendo la capacidad de personalizar cada página. Esto puede ayudarte a reducir la cantidad de archivos que debes mantener y mejorar la coherencia de tu documentación de API. Puedes definir metadatos y contenido para cada endpoint en tu especificación de OpenAPI y ubicar los endpoints donde quieras en la navegación.

​
Migración con la CLI

El comando mint migrate-mdx es la forma recomendada de migrar de páginas de endpoints en MDX a páginas autogeneradas. Este comando:
  • Analiza la estructura de navegación de tu docs.json.
  • Identifica las páginas MDX que generan páginas de endpoints de OpenAPI.
  • Extrae el contenido de archivos MDX y lo mueve a la extensión x-mint en tu especificación de OpenAPI.
  • Actualiza tu docs.json para referenciar directamente los endpoints de OpenAPI en lugar de archivos MDX.
  • Elimina los archivos MDX originales de endpoints.
Si ya tienes x-mint definido para un endpoint y también tienes una página MDX con contenido para ese endpoint, el contenido de MDX sobrescribirá la configuración existente de x-mint.Si tienes varias páginas MDX para el mismo endpoint con contenido diferente, el script usará el contenido de la página que aparezca última en tu docs.json.La herramienta de migración no admite previsualizar los cambios antes de aplicarlos.
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 deseas documentar.Cualquier página MDX que quieras migrar debe tener el frontmatter openapi: que haga referencia a un endpoint.
Valida tu archivo de OpenAPI usando el Swagger Editor o la Mint CLI.
2

Instala la Mint CLI

Si es necesario, instala o actualiza la Mint CLI.
3

Ejecuta el comando de migración.

mint migrate-mdx

​
Pasos de migración manual

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 quieres documentar.Para cualquier endpoint cuyo contenido o metadatos quieras personalizar, agrega la extensión x-mint al endpoint. Consulta x-mint extension para más detalles.Para los endpoints que quieras excluir de tu documentación, agrega la extensión x-hidden al endpoint.
Valida tu archivo de OpenAPI con el Swagger Editor o el Mint CLI.
2

Actualiza tu estructura de navegación.

Sustituye las referencias a páginas MDX por 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 la nueva navegación funciona correctamente, elimina los archivos de endpoint en MDX que ya no necesites.
Puedes personalizar cómo se muestra la documentación de tu API en la navegación.
Combina páginas de API generadas automáticamente con otras páginas: 
"navigation": {
  "groups": [
    {
      "group": "API Reference",
      "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 grupos: 
"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 navegación de OpenAPI ofrece mejor mantenibilidad y coherencia.