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 a partir de tu especificación de OpenAPI, conservando la personalización de las páginas individuales. Esto puede ayudarte a reducir la cantidad de archivos que debes mantener y a mejorar la coherencia de tu documentación de API. Puedes definir metadata y contenido para cada endpoint en tu especificación de OpenAPI y organizar los endpoints donde quieras en tu navigation.

​
Migración con la CLI

El comando mint migrate-mdx es la forma recomendada de migrar de páginas de endpoint en MDX a páginas autogeneradas. Este comando:
  • Analiza la estructura de navigation en 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 de última en tu docs.json.La herramienta de migración no admite la vista previa de 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 los endpoints cuyo metadata o contenido 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 la Mint CLI.
2

Actualiza tu estructura de navegación.

Reemplaza 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 tu nueva navegación funciona correctamente, elimina los archivos de endpoint en MDX que ya no necesites.
Puedes personalizar cómo aparece 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/autenticacion"
      ]
    }
  ]
}

​
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 individuales de MDX

Considera mantener páginas individuales de MDX cuando necesites:
  • Contenido personalizado amplio por endpoint, como componentes de React o ejemplos extensos.
  • 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 mejor mantenibilidad y coherencia.
⌘I