Migrar páginas de API en MDX a navegación de OpenAPI

Migra tus páginas de API escritas manualmente en MDX a documentación generada automáticamente desde OpenAPI, con navegación flexible y agrupación de endpoints.

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.

​

Patrones de navegación

Puedes personalizar cómo se muestra la documentación de tu API en tu navigation.

​

navigation de contenido mixto

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.