diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx index 60cc5eb0f..7324aa493 100644 --- a/api-playground/openapi-setup.mdx +++ b/api-playground/openapi-setup.mdx @@ -473,7 +473,7 @@ version: "version-string" (not required) -The method and path must exactly match your OpenAPI spec. If you have multiple OpenAPI specifications, include the path to the correct specification in your reference. You can also reference external OpenAPI URLs in `docs.json`. +The method and path must match your OpenAPI spec. Trailing slash differences are tolerated — `/users` and `/users/` resolve to the same endpoint. If your spec defines both as distinct operations, exact matching takes precedence. If you have multiple OpenAPI specifications, include the path to the correct specification in your reference. You can also reference external OpenAPI URLs in `docs.json`. #### Autogenerate endpoint pages diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx index 93d32f21d..26a1fb7f0 100644 --- a/api-playground/troubleshooting.mdx +++ b/api-playground/troubleshooting.mdx @@ -33,26 +33,13 @@ If your API pages aren't displaying correctly, check these common configuration This is usually caused by a misspelled `openapi` field in the page metadata. Make sure - the HTTP method and path match the HTTP method and path in the OpenAPI document exactly. + the HTTP method and path match the HTTP method and path in the OpenAPI document. - Here's an example of how things might go wrong: + Mintlify tolerates trailing slash differences, so `/users/{id}` and `/users/{id}/` resolve + to the same endpoint. However, if your spec defines both `/users/{id}` and `/users/{id}/` as + distinct operations, exact matching takes precedence. - ```mdx get-user.mdx - --- - openapi: "GET /users/{id}/" - --- - ``` - - ```yaml openapi.yaml - paths: - "/users/{id}": - get: ... - ``` - - Notice that the path in the `openapi` field has a trailing slash, whereas the path in the OpenAPI - document does not. - - Another common issue is a misspelled filename. If you are specifying a particular OpenAPI document + A common issue is a misspelled filename. If you are specifying a particular OpenAPI document in the `openapi` field, ensure the filename is correct. For example, if you have two OpenAPI documents `openapi/v1.json` and `openapi/v2.json`, your metadata might look like this: diff --git a/es/api-playground/openapi-setup.mdx b/es/api-playground/openapi-setup.mdx index b6e2c22b4..d6d4046f6 100644 --- a/es/api-playground/openapi-setup.mdx +++ b/es/api-playground/openapi-setup.mdx @@ -506,7 +506,7 @@ Crea una página para cada endpoint y especifica qué operación de OpenAPI most ``` -El método y la ruta deben coincidir exactamente con tu especificación de OpenAPI. Si tienes varias especificaciones de OpenAPI, incluye la ruta a la especificación correcta en tu referencia. También puedes hacer referencia a URLs externas de OpenAPI en `docs.json`. +El método y la ruta deben coincidir con tu especificación de OpenAPI. Las diferencias de barra diagonal final se toleran — `/users` y `/users/` se resuelven al mismo endpoint. Si tu especificación define ambos como operaciones distintas, la coincidencia exacta tiene prioridad. Si tienes varias especificaciones de OpenAPI, incluye la ruta a la especificación correcta en tu referencia. También puedes hacer referencia a URLs externas de OpenAPI en `docs.json`.
#### Generar automáticamente páginas de endpoints diff --git a/es/api-playground/troubleshooting.mdx b/es/api-playground/troubleshooting.mdx index 996c00700..87e85d696 100644 --- a/es/api-playground/troubleshooting.mdx +++ b/es/api-playground/troubleshooting.mdx @@ -34,23 +34,9 @@ Si sus páginas de la API no se muestran correctamente, revise estos problemas d Esto suele deberse a un campo `openapi` mal escrito en la metadata de la página. Asegúrate de que - el método HTTP y la ruta coincidan exactamente con el método HTTP y la ruta del documento de OpenAPI. + el método HTTP y la ruta coincidan con el método HTTP y la ruta del documento de OpenAPI. - Aquí tienes un ejemplo de cómo puede salir mal: - - ```mdx get-user.mdx - --- - openapi: "GET /users/{id}/" - --- - ``` - - ```yaml openapi.yaml - paths: - "/users/{id}": - get: ... - ``` - - Observa que la ruta en el campo `openapi` tiene una barra al final, mientras que la ruta en el documento de OpenAPI no la tiene. + Mintlify tolera las diferencias de barra diagonal final — `/users/{id}` y `/users/{id}/` se resuelven al mismo endpoint. Sin embargo, si tu especificación define ambos como operaciones distintas, la coincidencia exacta tiene prioridad. Otro problema común es un nombre de archivo mal escrito. Si especificas un documento de OpenAPI en particular en el campo `openapi`, asegúrate de que el nombre del archivo sea correcto. Por ejemplo, si tienes dos documentos de OpenAPI `openapi/v1.json` y `openapi/v2.json`, tu metadata podría verse así: diff --git a/fr/api-playground/openapi-setup.mdx b/fr/api-playground/openapi-setup.mdx index b965cccf0..05b4769a0 100644 --- a/fr/api-playground/openapi-setup.mdx +++ b/fr/api-playground/openapi-setup.mdx @@ -506,7 +506,7 @@ Créez une page pour chaque endpoint et indiquez quelle opération OpenAPI affic ``` -La méthode et le chemin doivent correspondre exactement à votre spécification OpenAPI. Si vous avez plusieurs spécifications OpenAPI, incluez le chemin vers la spécification correcte dans votre référence. Vous pouvez également référencer des URL OpenAPI externes dans `docs.json`. +La méthode et le chemin doivent correspondre à votre spécification OpenAPI. Les différences de barre oblique finale sont tolérées — `/users` et `/users/` correspondent au même endpoint. Si votre spécification définit les deux comme des opérations distinctes, la correspondance exacte a la priorité. Si vous avez plusieurs spécifications OpenAPI, incluez le chemin vers la spécification correcte dans votre référence. Vous pouvez également référencer des URL OpenAPI externes dans `docs.json`.
#### Générer automatiquement des pages d’endpoint diff --git a/fr/api-playground/troubleshooting.mdx b/fr/api-playground/troubleshooting.mdx index f75cbedd8..d23a8ad34 100644 --- a/fr/api-playground/troubleshooting.mdx +++ b/fr/api-playground/troubleshooting.mdx @@ -33,23 +33,9 @@ Si vos pages API ne s’affichent pas correctement, consultez ces problèmes de - Ceci est généralement dû à une faute d’orthographe du champ `openapi` dans la metadata de la page. Assurez-vous que la méthode HTTP et le chemin correspondent exactement à la méthode HTTP et au chemin dans le document OpenAPI. + Ceci est généralement dû à une faute d’orthographe du champ `openapi` dans la metadata de la page. Assurez-vous que la méthode HTTP et le chemin correspondent à la méthode HTTP et au chemin dans le document OpenAPI. - Voici un exemple de la façon dont cela peut mal tourner : - - ```mdx get-user.mdx - --- - openapi: "GET /users/{id}/" - --- - ``` - - ```yaml openapi.yaml - paths: - "/users/{id}": - get: ... - ``` - - Notez que le chemin dans le champ `openapi` se termine par une barre oblique, alors que le chemin dans le document OpenAPI n’en a pas. + Mintlify tolère les différences de barre oblique finale — `/users/{id}` et `/users/{id}/` correspondent au même endpoint. Cependant, si votre spécification définit les deux comme des opérations distinctes, la correspondance exacte a la priorité. Un autre problème fréquent est une erreur dans le nom de fichier. Si vous indiquez un document OpenAPI précis dans le champ `openapi`, assurez-vous que le nom de fichier est correct. Par exemple, si vous avez deux documents OpenAPI `openapi/v1.json` et `openapi/v2.json`, vos metadata pourraient ressembler à ceci : diff --git a/zh/api-playground/openapi-setup.mdx b/zh/api-playground/openapi-setup.mdx index 6862ec615..fd67e8a8f 100644 --- a/zh/api-playground/openapi-setup.mdx +++ b/zh/api-playground/openapi-setup.mdx @@ -506,7 +506,7 @@ API playground 会使用这些服务器 URL 来确定请求的发送目标。如 ``` -方法和路径必须与您的 OpenAPI 规范完全一致。若您有多个 OpenAPI 规范，请在引用中包含对应规范文件的路径。您也可以在 `docs.json` 中引用外部 OpenAPI URL。 +方法和路径必须与您的 OpenAPI 规范一致。末尾斜杠的差异是可以容忍的——`/users` 和 `/users/` 会解析到同一个端点。如果您的规范将两者定义为不同的操作，精确匹配优先。若您有多个 OpenAPI 规范，请在引用中包含对应规范文件的路径。您也可以在 `docs.json` 中引用外部 OpenAPI URL。
#### 自动生成端点页面 diff --git a/zh/api-playground/troubleshooting.mdx b/zh/api-playground/troubleshooting.mdx index d3dfbaf51..29d6fbd6b 100644 --- a/zh/api-playground/troubleshooting.mdx +++ b/zh/api-playground/troubleshooting.mdx @@ -31,23 +31,9 @@ keywords: ["API 故障排查", "OpenAPI 无效", "配置问题"] 这通常是由于页面 metadata 中的 `openapi` 字段拼写错误导致的。请确保 - HTTP 方法和路径与 OpenAPI 文档中的 HTTP 方法和路径完全一致。 + HTTP 方法和路径与 OpenAPI 文档中的 HTTP 方法和路径一致。 - 下面是一个可能出错的示例： - - ```mdx get-user.mdx - --- - openapi: "GET /users/{id}/" - --- - ``` - - ```yaml openapi.yaml - paths: - "/users/{id}": - get: ... - ``` - - 请注意，`openapi` 字段中的路径以斜杠结尾，而 OpenAPI 文档中的路径没有。 + Mintlify 可以容忍末尾斜杠的差异——`/users/{id}` 和 `/users/{id}/` 会解析到同一个端点。但是，如果你的规范将两者定义为不同的操作，精确匹配优先。 另一个常见问题是文件名拼写错误。如果你在 `openapi` 字段中指定了某个特定的 OpenAPI 文档，请确保文件名正确。例如，如果你有两个 OpenAPI 文档 `openapi/v1.json` 和 `openapi/v2.json`，你的 metadata 可能如下所示：