Saltar al contenido principal
Si actualmente usas páginas individuales en MDX para tus endpoints de API, puedes migrar a la generación automática de páginas desde tu especificación de OpenAPI, manteniendo la personalización de las páginas individuales. Esto puede ayudarte a reducir la cantidad de archivos que necesitas 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 endpoints 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 los archivos MDX y lo mueve a la extensión x-mint en tu especificación de OpenAPI.
  • Actualiza tu docs.json para hacer referencia directamente a los endpoints de OpenAPI en lugar de a archivos MDX.
  • Elimina los archivos MDX de endpoints originales.
Si ya tienes x-mint definido para un endpoint y también tienes una página MDX con contenido para ese endpoint, el contenido 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 quieres 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 deseas documentar.Para cualquier endpoint cuyo metadata o contenido quieras personalizar, añade la extensión x-mint al endpoint. Consulta extensión x-mint para más detalles.Para cualquier endpoint 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 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 MDX 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 individuales de MDX

Considera mantener páginas individuales de MDX 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 facilidad de mantenimiento y coherencia.
⌘I