Saltar al contenido principal
Las páginas de endpoints generadas toman su título, descripción, parámetros y respuestas de tu especificación OpenAPI. Para cambiar lo que muestra una página, puedes:
  • Agregar la extensión x-mint a la operación en tu especificación. Tus páginas siguen generándose y los cambios se guardan junto con tu especificación.
  • Crear una página MDX para el endpoint. Úsala para unas pocas páginas que necesiten diseños personalizados o para probar cambios en una página.
Para cambiar la URL de una página, consulta URLs y títulos de endpoints.

Sobrescribir los metadatos de la página

Agrega x-mint.metadata a una operación para sobrescribir el frontmatter de la página. Puedes usar cualquier campo válido en el frontmatter de MDX excepto openapi.
Usa x-mint.metadata para definir por endpoint la visualización del playground, los grupos de acceso o una píldora tag en la barra lateral.

Agregar contenido a una página

Agrega contenido Markdown y MDX antes de la documentación de API generada con x-mint.content. El contenido admite todos los componentes de Mintlify.

Contraer los campos del playground

Para que los campos de objetos anidados aparezcan contraídos en el playground, configura x-mint.playground.expand como false en una operación. Las secciones Authorization, Headers, Query, Path y Body, y el objeto de cuerpo de nivel superior, permanecen expandidos, así que los lectores solo expanden los campos anidados que necesitan. De forma predeterminada, los campos de objetos están expandidos.
Para controlar cómo se muestran los campos opcionales en todos los endpoints, usa api.optional en tu docs.json.

Agregar píldoras de parámetros

Etiqueta los parámetros con píldoras personalizadas usando x-mint.pre y x-mint.post en cualquier esquema. Las píldoras de pre aparecen antes del nombre del parámetro y las de post aparecen después, junto a las píldoras integradas como required, read-only y write-only. Cada cadena del array se convierte en su propia píldora.
Para mostrar un campo de tu especificación como píldora en cada parámetro que lo tenga, enumera la clave del campo en api.params.post en tu docs.json:
docs.json
Con esta configuración, una propiedad como { "type": "string", "nullable": true, "x-internal": "admin" } muestra las píldoras nullable y admin junto a su nombre. Las píldoras posteriores aparecen en este orden: primero las integradas, después las de api.params.post y por último las de x-mint.post de cada propiedad.

Crear páginas MDX para endpoints

Crea una página MDX para un endpoint cuando quieras control total sobre una página, pero sigas queriendo parámetros y respuestas generados. Configura el campo de frontmatter openapi con la operación que documenta la página.
El valor de openapi debe ser una sola cadena que haga referencia a un endpoint. Si lo configuras como una lista de endpoints u otro valor que no sea una cadena, el despliegue falla. El método y la ruta deben coincidir exactamente con tu especificación OpenAPI. Agrega la página a tu navegación como cualquier otra página. No enumeres también la misma operación, como "GET /users", en tu navegación.
Incluye siempre la ruta del archivo de la especificación cuando tengas más de una especificación OpenAPI en tu repositorio.Mintlify sube todas las especificaciones OpenAPI de tu repositorio de documentación, incluso si docs.json no hace referencia a ellas. Si una página MDX usa openapi: "METHOD /path" sin una ruta de archivo, Mintlify busca una operación coincidente en todas las especificaciones subidas. Si más de una especificación contiene el mismo método y ruta, prevalece la primera coincidencia en orden alfabético de nombre de archivo.Para evitar una coincidencia incorrecta, incluye la ruta del archivo en el frontmatter, genera las páginas desde docs.json o elimina las especificaciones que ya no necesites.
Para crear archivos MDX para todos los endpoints de una especificación, usa el scraper de Mintlify. Agrega -o para elegir la carpeta de salida. Sin esta opción, los archivos se guardan en el directorio actual.
Para volver a convertir páginas de endpoints MDX existentes en páginas generadas, consulta Migrar páginas de API MDX a OpenAPI.

Crear páginas para modelos de datos

Crea una página para un esquema de components.schemas de tu especificación con el campo de frontmatter openapi-schema.
Si esquemas de más de una especificación comparten nombre, incluye la ruta del archivo: