mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
2ccd573b95
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
119 lines
3.7 KiB
Plaintext
119 lines
3.7 KiB
Plaintext
---
|
|
title: "Migrar páginas de API en MDX a navegación de OpenAPI"
|
|
sidebarTitle: "Migrar de MDX a OAS"
|
|
description: "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."
|
|
keywords: ["Migración de API", "Migración de OpenAPI", "Extensión x-mint"]
|
|
---
|
|
|
|
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. |