users y el summary Get user obtiene la URL /api-reference/users/get-user.
- Directory: el
directoryque configuras en el campoopenapide tudocs.json, en minúsculas. El valor predeterminado esapi-reference. - Tag: el
namedel tag de la operación. Las etiquetas dex-group,x-displayNameo elsummaryde un tag 3.2 no cambian la URL. Si una operación no tiene tags, la URL no tiene la parte del tag. Para saber qué tag usa Mintlify cuando una operación tiene varios, consulta Anidar grupos con jerarquías de tags. Los tags padre de OpenAPI 3.2 no agregan partes a la URL. - Slug: el
summaryde la operación, convertido para usarse en una URL. Si la operación no tiene summary, Mintlify usa el método HTTP y la ruta. Por ejemplo,GET /users/{id}/postsse convierte enget-users-posts.
{, }, (, ), ,, ., ' y /, y convierte el resultado a minúsculas. Otros caracteres, como ?, &, : y las letras que no son ASCII, permanecen en la URL. Para obtener URLs predecibles, usa summaries y nombres de tags formados por letras, números y espacios, o usa IDs de operación.
Si dos endpoints del mismo grupo producen la misma URL, Mintlify agrega -1, -2, y así sucesivamente, a los posteriores. En algunos casos, una página reemplaza a la otra sin mostrar ningún error:
- Dos especificaciones que comparten un
directory, o la misma especificación usada en dos lugares de tu navegación. - Un endpoint con
x-hiddenque produce la misma URL que otro endpoint.
directory.
Configura slug como operationId para crear el slug a partir del operationId de cada operación en lugar de su summary. Así podrás editar los summaries sin cambiar las URLs.
docs.json
getActions se convierte en get-actions y create_action en create-action. Mintlify elimina cualquier carácter que no sea una letra o un número ASCII. Las operaciones sin operationId usan el summary. Las partes del directory y del tag no cambian.
Agrega x-mint.href a una operación para definir su URL completa. La URL reemplaza el directory, el tag y el slug.
. del segmento final, así que /reference/v1.2 se convierte en /reference/v1. No uses puntos en el segmento final.
El título de una página generada es el summary de la operación. Si no hay summary, Mintlify crea el título a partir del slug de la URL. Para definir un título o una etiqueta de barra lateral distintos, usa x-mint.metadata:
New PR Opened da el título New pr opened. Configura x-mint.metadata.title para conservar el formato del summary.
Si usas la misma especificación en más de un idioma, todos los idiomas enlazan a las mismas páginas, a menos que cada uno tenga su propio directory. Para generar páginas separadas para cada idioma, por ejemplo a partir de una especificación traducida, configura un directory distinto para cada idioma.
Los summaries traducidos producen slugs distintos, por lo que la URL de una página difiere entre idiomas, a menos que uses IDs de operación.
Para evitar romper enlaces cuando cambie tu especificación:
- Configura
slugcomooperationIdy mantén estables los IDs de operación. - Mantén estables los nombres de los tags. Usa
x-grouppara cambiar la etiqueta de un grupo sin cambiar las URLs. - Usa
x-mint.hrefpara los endpoints cuya URL nunca debe cambiar. - Cuando una URL cambie, agrega una redirección desde la URL anterior.