Saltar al contenido principal
Si actualmente usas páginas individuales en MDX para los endpoints de tu API, puedes migrar a la generación automática de páginas 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 consistencia de tu documentación de API. Puedes definir metadatos y contenido para cada endpoint en tu especificación de OpenAPI y organizar 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 los archivos MDX y lo traslada 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 los archivos MDX.
  • Elimina los archivos originales de endpoints en MDX.
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 de ú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 CLI de Mint.
2

Instala la CLI de Mint

Si es necesario, instala o actualiza la CLI de Mint.
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 los endpoints cuyos metadatos o contenido quieras personalizar, añade la extensión x-mint al endpoint. Consulta extensión x-mint para más detalles.Para los endpoints que quieras excluir de tu documentación, añade la extensión x-hidden al endpoint.
Valida tu archivo de OpenAPI usando el Swagger Editor o la CLI de Mint.
2

Actualiza tu estructura de navegación.

Reemplaza las referencias de 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 tu nueva navegación funcione correctamente, elimina los archivos de endpoint 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": "Referencia de la API",
      "openapi": "openapi.json",
      "pages": [
        "api/overview",
        "GET /users",
        "POST /users", 
        "api/autenticación"
      ]
    }
  ]
}

​
Varias versiones de 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.