users et le summary Get user obtient l’URL /api-reference/users/get-user.
- Directory : le
directoryque vous définissez sur le champopenapide votredocs.json, en minuscules. La valeur par défaut estapi-reference. - Tag : le
namedu tag de l’opération. Les libellés provenant dex-group,x-displayNameou dusummaryd’un tag 3.2 ne modifient pas l’URL. Si une opération n’a pas de tag, l’URL n’a pas de partie tag. Pour savoir quel tag Mintlify utilise lorsqu’une opération en a plusieurs, consultez Imbriquer des groupes avec des hiérarchies de tags. Les tags parents d’OpenAPI 3.2 n’ajoutent pas de partie à l’URL. - Slug : le
summaryde l’opération, converti pour être utilisé dans une URL. Si l’opération n’a pas de summary, Mintlify utilise la méthode HTTP et le chemin. Par exemple,GET /users/{id}/postsdevientget-users-posts.
{, }, (, ), ,, ., ' et /, puis met le résultat en minuscules. Les autres caractères, comme ?, &, : et les lettres non ASCII, restent dans l’URL. Pour obtenir des URL prévisibles, utilisez des summaries et des noms de tags composés de lettres, de chiffres et d’espaces, ou utilisez des ID d’opération.
Si deux endpoints du même groupe produisent la même URL, Mintlify ajoute -1, -2, et ainsi de suite, aux suivants. Dans certains cas, une page remplace l’autre, sans erreur :
- Deux spécifications qui partagent un
directory, ou la même spécification utilisée à deux endroits de votre navigation. - Un endpoint avec
x-hiddenqui produit la même URL qu’un autre endpoint.
directory.
Définissez slug sur operationId pour construire le slug à partir de l’operationId de chaque opération plutôt que de son summary. Vous pourrez alors modifier les summaries sans changer les URL.
docs.json
getActions devient get-actions et create_action devient create-action. Mintlify supprime tout caractère qui n’est pas une lettre ou un chiffre ASCII. Les opérations sans operationId utilisent le summary. Les parties directory et tag ne changent pas.
Ajoutez x-mint.href à une opération pour définir son URL complète. L’URL remplace le directory, le tag et le slug.
. du segment final : /reference/v1.2 devient /reference/v1. N’utilisez pas de points dans le segment final.
Le titre d’une page générée est le summary de l’opération. S’il n’y a pas de summary, Mintlify construit le titre à partir du slug de l’URL. Pour définir un titre ou un libellé de barre latérale différent, utilisez x-mint.metadata :
New PR Opened donne le titre New pr opened. Définissez x-mint.metadata.title pour conserver la mise en forme du summary.
Si vous utilisez la même spécification dans plusieurs langues, toutes les langues renvoient vers les mêmes pages, sauf si chacune a son propre directory. Pour générer des pages distinctes pour chaque langue, par exemple à partir d’une spécification traduite, définissez un directory différent pour chaque langue.
Les summaries traduits produisent des slugs différents : l’URL d’une page diffère donc d’une langue à l’autre, sauf si vous utilisez des ID d’opération.
Pour éviter de casser des liens lorsque votre spécification change :
- Définissez
slugsuroperationId, et gardez des ID d’opération stables. - Gardez des noms de tags stables. Utilisez
x-grouppour changer le libellé d’un groupe sans modifier les URL. - Utilisez
x-mint.hrefpour les endpoints dont l’URL ne doit jamais changer. - Lorsqu’une URL change, ajoutez une redirection depuis l’ancienne URL.