> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.manicule.dev/es/llms.txt
> Use this file to discover all available pages before exploring further.
> For every page in one file, fetch https://mintlify.manicule.dev/es/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://mintlify.manicule.dev/api/mcp.
> Every agent surface: https://mintlify.manicule.dev/.well-known/llms-manifest.json

# Migrar páginas de API en MDX a navegación de OpenAPI (/es/guides/migrating-from-mdx)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 890 · updated: 2026-07-31 -->
Related: [Crea un assistant dentro de tu aplicación](/es/guides/assistant-embed.md), [Configurar automerge para aplicaciones GitHub](/es/guides/configure-automerge.md), [Usar automatizaciones](/es/guides/use-automations.md), [Escribe documentación con Claude Code](/es/guides/claude-code.md), [Escribe documentación con Codex](/es/guides/codex.md), [Escribe documentación con Cursor](/es/guides/cursor.md)

> 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.

<div id="migration-steps">
  ## Pasos de migración
</div>

<Steps>
  <Step title="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](/es/api-playground/openapi-setup#customize-your-endpoint-pages) para más detalles.

    Para cualquier endpoint que quieras excluir de tu documentación, agrega la extensión `x-hidden` al endpoint.

<Info>Valida tu archivo OpenAPI usando el [Swagger Editor](https://editor.swagger.io/) o la [CLI de Mint](https://www.npmjs.com/package/mint).</Info>
  </Step>

  <Step title="Actualiza tu estructura de navegación.">
    Reemplaza las referencias a páginas MDX con endpoints de OpenAPI en tu `docs.json`.

    ```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"
          ]
        }
      ]
    }
    ```
  </Step>

<Step title="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.</Step>
</Steps>

<div id="navigation-patterns">
  ## Patrones de navegación
</div>

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

<div id="mixed-content-navigation">
  ### navigation de contenido mixto
</div>

Combina páginas de API generadas automáticamente con otras páginas:

```json
"navigation": {
  "groups": [
    {
      "group": "Referencia de API",
      "openapi": "openapi.json",
      "pages": [
        "api/overview",
        "GET /users",
        "POST /users", 
        "api/authentication"
      ]
    }
  ]
}
```

<div id="multiple-api-versions">
  ### Varias versiones de la API
</div>

Organiza distintas versiones de la API usando pestañas o groups:

```json
"navigation": {
  "tabs": [
    {
      "tab": "API v1",
      "openapi": "specs/v1.json"
    },
    {
      "tab": "API v2", 
      "openapi": "specs/v2.json"
    }
  ]
}
```

<div id="when-to-use-individual-mdx-pages">
  ## Cuándo usar páginas MDX individuales
</div>

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.