> ## Documentation Index
> Fetch the complete documentation index at: https://omer-914cc1c6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Migración de páginas de API en MDX a navigation de OpenAPI

> Actualiza de páginas individuales de endpoints en MDX a una generación automatizada con OpenAPI y navigation flexible

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.

<div id="cli-migration">
  ## Migración con la CLI
</div>

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.

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

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

    Cualquier página MDX que quieras migrar debe tener el frontmatter `openapi:` que haga referencia a un endpoint.

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

  <Step title="Instala la Mint CLI">
    Si es necesario, instala o actualiza la [Mint CLI](/es/installation).
  </Step>

  <Step title="Ejecuta el comando de migración.">
    ```bash theme={null}
    mint migrate-mdx
    ```
  </Step>
</Steps>

<div id="manual-migration-steps">
  ## Pasos de migración manual
</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 quieres documentar.

    Para los endpoints cuyo metadata o contenido quieras personalizar, agrega la extensión `x-mint` al endpoint. Consulta [x-mint extension](/es/api-playground/openapi-setup#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.

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

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

    ```json theme={null}
    "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 de endpoint en `MDX` que ya no necesites.
  </Step>
</Steps>

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

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

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

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

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

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

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

```json theme={null}
"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 individuales de `MDX`
</div>

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.