- ## Rellenar automáticamente las páginas de la API
+ ## Rellenar automáticamente páginas de API
-Agrega un campo `openapi` a cualquier elemento de navigation en tu `docs.json` para generar automáticamente páginas para endpoints de OpenAPI. Puedes controlar dónde aparecen estas páginas en tu estructura de navegación, ya sea como secciones de API dedicadas o junto con otras páginas.
+Agrega un campo `openapi` a cualquier elemento de `navigation` en tu `docs.json` para generar automáticamente páginas para endpoints de OpenAPI. Puedes controlar dónde aparecen estas páginas en tu estructura de navegación, ya sea como secciones de API dedicadas o junto con otras páginas.
El campo `openapi` acepta una ruta de archivo en tu repositorio de documentación o una URL a un documento de OpenAPI hospedado.
@@ -293,20 +293,20 @@ Las páginas de endpoints generadas tienen estos valores de metadata predetermin
- #### Definir una especificación OpenAPI predeterminada
+ #### Configurar una especificación de OpenAPI predeterminada
-Configura una especificación OpenAPI predeterminada para un elemento de navigation. Luego, haz referencia a endpoints específicos en el campo `pages`:
+Configura una especificación de OpenAPI predeterminada para un elemento de navigation. Luego, haz referencia a endpoints específicos en el campo `pages`:
```json {12, 15-16}
"navigation": {
@@ -389,13 +387,13 @@ Configura una especificación OpenAPI predeterminada para un elemento de navigat
}
```
-Cualquier entrada de página que coincida con el formato `METHOD /path` generará una página de API para ese endpoint usando la especificación de OpenAPI predeterminada.
+Cualquier entrada de página que coincida con el formato `METHOD /path` generará una página de API para ese endpoint usando la especificación OpenAPI predeterminada.
- #### Herencia de la especificación de OpenAPI
+ #### Herencia de especificaciones de OpenAPI
-Las especificaciones de OpenAPI se heredan a lo largo de la jerarquía de navigation. Los elementos de navigation secundarios heredan la especificación de OpenAPI de su elemento principal, a menos que definan la suya propia:
+Las especificaciones de OpenAPI se heredan a lo largo de la jerarquía de navigation. Los elementos secundarios de navigation heredan la especificación de OpenAPI de su elemento padre, a menos que definan la suya propia:
```json {3, 7-8, 11, 13-14}
{
@@ -422,28 +420,28 @@ Las especificaciones de OpenAPI se heredan a lo largo de la jerarquía de naviga
#### Endpoints individuales
-Haz referencia a endpoints específicos sin establecer una especificación de OpenAPI predeterminada, incluyendo la ruta del archivo:
+Hace referencia a endpoints específicos sin establecer una especificación de OpenAPI predeterminada, incluyendo la ruta del archivo:
```json {5-6}
"navigation": {
"pages": [
- "introduccion",
- "guias-de-usuario",
+ "introduction",
+ "user-guides",
"/path/to/openapi-v1.json POST /users",
"/path/to/openapi-v2.json GET /orders"
]
}
```
-Este enfoque es útil cuando necesitas endpoints individuales de distintas especificaciones o solo quieres incluir algunos endpoints seleccionados.
+Este enfoque es útil cuando necesitas endpoints individuales de distintas especificaciones o solo quieres incluir endpoints específicos.
- ## Crear archivos `MDX` para páginas de la API
+ ## Crear archivos `MDX` para páginas de API
Para controlar páginas de endpoints individuales, crea páginas `MDX` para cada operación. Esto te permite personalizar la metadata de la página, agregar contenido, omitir ciertas operaciones o reordenar páginas en tu navigation a nivel de página.
-Consulta un [ejemplo de página MDX de OpenAPI de MindsDB](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx?plain=1) y cómo aparece en su [documentación en vivo](https://docs.mindsdb.com/rest/databases/create-databases).
+Consulta un [ejemplo de página MDX de OpenAPI de MindsDB](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx?plain=1) y cómo aparece en su [documentación pública](https://docs.mindsdb.com/rest/databases/create-databases).
### Especificar archivos manualmente
@@ -451,30 +449,30 @@ Consulta un [ejemplo de página MDX de OpenAPI de MindsDB](https://github.com/mi
Crea una página `MDX` para cada endpoint y especifica qué operación de OpenAPI mostrar usando el campo `openapi` en el frontmatter.
-Cuando haces referencia a una operación de OpenAPI de esta manera, el nombre, la descripción, los parámetros, las respuestas y el área de pruebas de la API se generan automáticamente a partir de tu documento de OpenAPI.
+Cuando haces referencia a una operación de OpenAPI de esta forma, el nombre, la descripción, los parámetros, las respuestas y el área de pruebas de la API se generan automáticamente a partir de tu documento de OpenAPI.
Si tienes varios archivos de OpenAPI, incluye la ruta del archivo en tu referencia para asegurarte de que Mintlify encuentre el documento de OpenAPI correcto. Si solo tienes un archivo de OpenAPI, Mintlify lo detectará automáticamente.
- Este enfoque funciona independientemente de si configuraste una especificación de OpenAPI
- predeterminada en tu navigation. Puedes referenciar cualquier endpoint de cualquier
- especificación de OpenAPI incluyendo la ruta del archivo en el frontmatter.
+ Este enfoque funciona independientemente de si has establecido una especificación de OpenAPI predeterminada
+ en tu navigation. Puedes hacer referencia a cualquier endpoint de cualquier especificación de OpenAPI
+ si incluyes la ruta del archivo en el frontmatter.
-Si deseas referenciar un archivo de OpenAPI externo, agrega la URL del archivo a tu `docs.json`.
+Si quieres hacer referencia a un archivo de OpenAPI externo, agrega la URL del archivo a tu `docs.json`.
- ```mdx Ejemplo
+ ```mdx Example
---
title: "Get users"
- description: "Returns all plants from the system that the user has access to"
+ description: "Devuelve todas las plantas del sistema a las que el usuario tiene acceso"
openapi: "/path/to/openapi-1.json GET /users"
deprecated: true
version: "1.0"
---
```
- ```mdx Formato
+ ```mdx Format
---
title: "title of the page"
description: "description of the page"
@@ -486,40 +484,40 @@ Si deseas referenciar un archivo de OpenAPI externo, agrega la URL del archivo a
- El método y la ruta deben coincidir exactamente con la definición en tu
- especificación de OpenAPI. Si el endpoint no existe en el archivo de OpenAPI, la página
- quedará vacía.
+ El método y la ruta deben coincidir exactamente con la definición de tu
+ especificación de OpenAPI. Si el endpoint no existe en el archivo de OpenAPI,
+ la página quedará vacía.
- ### Generar archivos `MDX` automáticamente
+ ### Autogenerar archivos `MDX`
-Usa nuestro [scraper](https://www.npmjs.com/package/@mintlify/scraping) de Mintlify para generar automáticamente páginas `MDX` para documentos extensos de OpenAPI.
+Usa nuestro [scraper](https://www.npmjs.com/package/@mintlify/scraping) de Mintlify para autogenerar páginas `MDX` para documentos OpenAPI de gran tamaño.
- Tu documento de OpenAPI debe ser válido o los archivos no se generarán automáticamente.
+ Tu documento OpenAPI debe ser válido o no se generarán los archivos automáticamente.
El scraper genera:
-* Una página `MDX` por cada operación en el campo `paths` de tu documento de OpenAPI.
-* Si tu documento de OpenAPI es versión 3.1+, una página `MDX` por cada operación en el campo `webhooks` de tu documento de OpenAPI.
+* Una página `MDX` por cada operación en el campo `paths` de tu documento OpenAPI.
+* Si tu documento OpenAPI es versión 3.1+, una página `MDX` por cada operación en el campo `webhooks` de tu documento OpenAPI.
* Un arreglo de entradas de navigation que puedes agregar a tu `docs.json`.
-
+
```bash
npx @mintlify/scraping@latest openapi-file
```
-
+
```bash
npx @mintlify/scraping@latest openapi-file -o api-reference
```
- Agrega la bandera `-o` para especificar una carpeta en la que generar los archivos. Si no se especifica una carpeta, los archivos se generarán en el directorio de trabajo.
+ Agrega la opción `-o` para indicar la carpeta donde se crearán los archivos. Si no se especifica una carpeta, los archivos se crearán en el directorio de trabajo.
@@ -543,25 +541,41 @@ Puedes crear páginas individuales para cualquier esquema de OpenAPI definido en
```
+Si tienes esquemas con el mismo nombre en varios archivos, también puedes especificar el archivo de OpenAPI:
+
+
+ ```mdx Ejemplo
+ ---
+ openapi-schema: en-schema.json OrderItem
+ ---
+ ```
+
+ ```mdx Formato
+ ---
+ openapi-schema: "path-to-schema-file schema-key"
+ ---
+ ```
+
+
## Webhooks
-Los webhooks son callbacks HTTP que tu API envía para notificar a sistemas externos cuando se producen eventos. Los webhooks son compatibles en documentos de OpenAPI 3.1+.
+Los webhooks son devoluciones de llamada HTTP que tu API envía para notificar a sistemas externos cuando se producen eventos. Los webhooks son compatibles con documentos de OpenAPI 3.1+.
### Define webhooks en tu especificación de OpenAPI
-Agrega un campo `webhooks` a tu documento de OpenAPI junto con el campo `paths`.
+Añade un campo `webhooks` a tu documento de OpenAPI junto con el campo `paths`.
Para obtener más información sobre cómo definir webhooks, consulta [Webhooks](https://spec.openapis.org/oas/v3.1.0#oasWebhooks) en la documentación de OpenAPI.
- ### Referencia webhooks en archivos MDX
+ ### Referencia de webhooks en archivos MDX
-Al crear páginas MDX para webhooks, usa `webhook` en lugar de métodos HTTP como `GET` o `POST`:
+Al crear páginas MDX para webhooks, utiliza `webhook` en lugar de métodos HTTP como `GET` o `POST`:
```mdx
---
diff --git a/fr/api-playground/openapi-setup.mdx b/fr/api-playground/openapi-setup.mdx
index 3940c69be..761110af5 100644
--- a/fr/api-playground/openapi-setup.mdx
+++ b/fr/api-playground/openapi-setup.mdx
@@ -1,10 +1,10 @@
---
title: "Configuration d’OpenAPI"
-description: "Faites référence à des endpoints OpenAPI dans vos pages de documentation"
+description: "Référencez des points de terminaison OpenAPI dans vos pages de documentation"
icon: "file-json"
---
-OpenAPI est une spécification de description d’API. Mintlify prend en charge les documents OpenAPI 3.0+ pour générer une documentation d’API interactive et la maintenir à jour.
+OpenAPI est une spécification pour décrire des API. Mintlify prend en charge les documents OpenAPI 3.0+ pour générer une documentation d’API interactive et la maintenir à jour.
## Ajouter un fichier de spécification OpenAPI
@@ -12,30 +12,32 @@ OpenAPI est une spécification de description d’API. Mintlify prend en charge
Pour documenter vos endpoints avec OpenAPI, vous avez besoin d’un document OpenAPI valide au format JSON ou YAML conforme à la [spécification OpenAPI 3.0+](https://swagger.io/specification/).
-Vous pouvez créer des pages d’API à partir d’un ou de plusieurs documents OpenAPI.
+Vous pouvez créer des pages API à partir d’un ou de plusieurs documents OpenAPI.
### Décrire votre API
-Nous recommandons les ressources suivantes pour apprendre et concevoir vos documents OpenAPI.
+Nous recommandons les ressources suivantes pour apprendre et rédiger vos documents OpenAPI.
-* [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/v3_0/basic-structure/) pour apprendre la syntaxe OpenAPI.
-* [The OpenAPI specification Markdown sources](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/) pour consulter les détails de la dernière spécification OpenAPI.
+* [Guide OpenAPI de Swagger](https://swagger.io/docs/specification/v3_0/basic-structure/) pour apprendre la syntaxe OpenAPI.
+* [Sources Markdown de la spécification OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/) pour consulter les détails de la dernière version de la spécification OpenAPI.
* [Swagger Editor](https://editor.swagger.io/) pour modifier, valider et déboguer votre document OpenAPI.
-* [The Mint CLI](https://www.npmjs.com/package/mint) pour valider votre document OpenAPI avec la commande : `mint openapi-check
`.
+* [La CLI Mint](https://www.npmjs.com/package/mint) pour valider votre document OpenAPI avec la commande : `mint openapi-check `.
- Swagger's OpenAPI Guide est destiné à OpenAPI v3.0, mais presque toutes les informations
- s’appliquent à la v3.1. Pour plus d’informations sur les différences entre la v3.0
- et la v3.1, voir [Migrating from OpenAPI 3.0 to
+ Le Guide OpenAPI de Swagger porte sur OpenAPI v3.0, mais presque toutes les informations
+ s’appliquent à la v3.1. Pour en savoir plus sur les différences entre la v3.0
+ et la v3.1, consultez l’article [Migrating from OpenAPI 3.0 to
3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0)
sur le blog OpenAPI.
-### Spécifier l'URL de votre API
+
+ ### Spécifier l’URL de votre API
+
-Pour activer des fonctionnalités Mintlify comme le bac à sable d’API, ajoutez un champ `servers` à votre document OpenAPI avec l’URL de base de votre API.
+Pour activer les fonctionnalités de Mintlify, comme le bac à sable d’API, ajoutez un champ `servers` à votre document OpenAPI avec l’URL de base de votre API.
```json
{
@@ -47,23 +49,23 @@ Pour activer des fonctionnalités Mintlify comme le bac à sable d’API, ajoute
}
```
-Dans un document OpenAPI, les différents endpoints d’API sont définis par leurs chemins, comme `/users/{id}` ou simplement `/`. L’URL de base indique où ces chemins doivent être ajoutés. Pour plus d’informations sur la configuration du champ `servers`, consultez [API Server and Base Path](https://swagger.io/docs/specification/api-host-and-base-path/) dans la documentation OpenAPI.
+Dans un document OpenAPI, les différents endpoints d’API sont définis par leurs chemins, comme `/users/{id}` ou simplement `/`. L’URL de base indique où rattacher ces chemins. Pour plus d’informations sur la configuration du champ `servers`, consultez [API Server and Base Path](https://swagger.io/docs/specification/api-host-and-base-path/) dans la documentation OpenAPI.
-Le bac à sable d’API utilise ces URL de serveur pour déterminer où envoyer les requêtes. Si vous spécifiez plusieurs serveurs, une liste déroulante permettra aux utilisateurs de basculer entre eux. Si vous ne spécifiez pas de serveur, le bac à sable d’API utilisera le mode simple puisqu’il ne peut pas envoyer de requêtes sans URL de base.
+Le bac à sable d’API utilise ces URL de serveur pour déterminer où envoyer les requêtes. Si vous spécifiez plusieurs serveurs, un menu déroulant permettra aux utilisateurs de basculer entre eux. Si vous ne spécifiez pas de serveur, le bac à sable d’API utilisera le mode simple puisqu’il ne peut pas envoyer de requêtes sans URL de base.
-Si votre API expose des endpoints à différentes URL, vous pouvez [remplacer le champ server](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers) pour un chemin ou une opération donnée.
+Si votre API comporte des endpoints disponibles à différentes URL, vous pouvez [remplacer le champ servers](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers) pour un chemin ou une opération donnée.
### Spécifier l’authentification
-Pour activer l’Authentification dans votre documentation et votre bac à sable d’API, configurez les champs `securitySchemes` et `security` dans votre document OpenAPI. Les descriptions d’API et le bac à sable d’API ajouteront des champs d’authentification en fonction des configurations de sécurité définies dans votre document OpenAPI.
+Pour activer l’authentification dans votre documentation d’API et votre bac à sable d’API, configurez les champs `securitySchemes` et `security` dans votre document OpenAPI. Les descriptions d’API et le bac à sable d’API ajouteront des champs d’authentification en fonction des configurations de sécurité définies dans votre document OpenAPI.
-
- Ajoutez un champ `securitySchemes` pour définir comment les utilisateurs s’authentifient.
+
+ Ajoutez un champ `securitySchemes` pour définir la façon dont les utilisateurs s’authentifient.
- Cet exemple montre une configuration pour l’authentification Bearer.
+ Cet exemple montre une configuration pour l’authentification bearer.
```json
{
@@ -79,8 +81,8 @@ Pour activer l’Authentification dans votre documentation et votre bac à sable
```
-
- Ajoutez un champ `security` pour exiger l’authentification.
+
+ Ajoutez un champ `security` pour rendre l’authentification obligatoire.
```json
{
@@ -94,27 +96,27 @@ Pour activer l’Authentification dans votre documentation et votre bac à sable
-Les types d’authentification courants incluent :
+Les types d’authentification courants incluent :
-* [API Keys](https://swagger.io/docs/specification/authentication/api-keys/) : pour les clés dans l’en-tête, la requête ou le cookie.
-* [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/) : pour les JWT (JSON Web Token) ou les jetons OAuth.
-* [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/) : pour le nom d’utilisateur et le mot de passe.
+* [API Keys](https://swagger.io/docs/specification/authentication/api-keys/) : pour les clés dans l’en-tête, la requête ou le cookie.
+* [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/) : pour les JWT (JSON Web Token) ou les jetons OAuth.
+* [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/) : pour le nom d’utilisateur et le mot de passe.
Si différents endpoints de votre API nécessitent différentes méthodes d’authentification, vous pouvez [remplacer le champ security](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.) pour une opération donnée.
-Pour plus d’informations sur la définition et l’application de l’authentification, consultez [Authentication](https://swagger.io/docs/specification/authentication/) dans la documentation OpenAPI.
+Pour plus d’informations sur la définition et l’application de l’authentification, consultez la section [Authentication](https://swagger.io/docs/specification/authentication/) de la documentation OpenAPI.
## Extension `x-mint`
-L’extension `x-mint` est une extension OpenAPI personnalisée qui offre un contrôle supplémentaire sur la manière dont la documentation de votre API est générée et affichée.
+L’extension `x-mint` est une extension OpenAPI personnalisée qui offre un contrôle supplémentaire sur la façon dont votre documentation d’API est générée et affichée.
- ### Metadata
+ ### Métadonnées
-Remplacez les metadata par défaut des pages d’API générées en ajoutant `x-mint: metadata` à n’importe quelle opération. Vous pouvez utiliser n’importe quel champ de metadata valide dans le frontmatter `MDX`, à l’exception de `openapi` :
+Outrepasser les métadonnées par défaut des pages d’API générées en ajoutant `x-mint: metadata` à n’importe quelle opération. Vous pouvez utiliser n’importe quel champ de métadonnées valide dans le frontmatter MDX, à l’exception de `openapi` :
```json {7-13}
{
@@ -167,13 +169,13 @@ Ajoutez du contenu avant la documentation de l’API générée automatiquement
}
```
-L’extension `content` prend en charge tous les composants MDX de Mintlify ainsi que leur mise en forme.
+L’extension `content` prend en charge tous les composants MDX de Mintlify ainsi que toute la mise en forme.
### Href
-Modifiez l’URL de la page d’endpoint dans votre documentation à l’aide de `x-mint: href` :
+Modifiez l’URL de la page d’endpoint dans votre documentation à l’aide de `x-mint: href` :
```json {6-8, 14-16}
{
@@ -198,28 +200,28 @@ Modifiez l’URL de la page d’endpoint dans votre documentation à l’aide de
}
```
-Lorsque `x-mint: href` est présent, l’entrée de navigation pointe directement vers l’URL spécifiée au lieu de générer une page d’API.
+Lorsque `x-mint: href` est présent, l’entrée de navigation pointe directement vers l’URL spécifiée au lieu de générer une page API.
### MCP
-Exposez sélectivement des endpoints en tant qu’outils Model Context Protocol (MCP) à l’aide de `x-mint: mcp`. N’activez que les endpoints sûrs pour un accès public via des outils d’IA.
+Exposez sélectivement des points de terminaison en tant qu’outils Model Context Protocol (MCP) à l’aide de `x-mint: mcp`. N’activez que ceux qui sont sûrs pour un accès public via des outils d’IA.
- La configuration MCP de l’endpoint.
+ La configuration MCP pour le point de terminaison.
- Indique s’il faut exposer l’endpoint en tant qu’outil MCP. Prend le pas sur la configuration au niveau du fichier.
+ Indique si le point de terminaison doit être exposé en tant qu’outil MCP. Prend le pas sur la configuration au niveau du fichier.
- Le nom de l’outil MCP.
+ Nom de l’outil MCP.
- La description de l’outil MCP.
+ Description de l’outil MCP.
@@ -275,36 +277,36 @@ Exposez sélectivement des endpoints en tant qu’outils Model Context Protocol
Pour en savoir plus, consultez [Model Context Protocol](/fr/ai/model-context-protocol).
- ## Renseigner automatiquement les pages d’API
+ ## Remplir automatiquement les pages d’API
-Ajoutez un champ `openapi` à tout élément de navigation dans votre `docs.json` pour générer automatiquement des pages pour les endpoints OpenAPI. Vous pouvez contrôler l’emplacement de ces pages dans votre structure de navigation, soit en sections API dédiées, soit aux côtés d’autres pages.
+Ajoutez un champ `openapi` à n’importe quel élément de navigation dans votre `docs.json` pour générer automatiquement des pages pour les endpoints OpenAPI. Vous pouvez contrôler l’emplacement de ces pages dans votre structure de navigation, soit en tant que sections d’API dédiées, soit aux côtés d’autres pages.
Le champ `openapi` accepte soit un chemin de fichier dans votre dépôt de documentation, soit une URL vers un document OpenAPI hébergé.
-Les pages d’endpoint générées comportent par défaut les metadata suivantes :
+Les pages d’endpoint générées ont les valeurs de metadata par défaut suivantes :
-* `title` : Le champ `summary` de l’opération, s’il est présent. S’il n’y a pas de `summary`, le titre est généré à partir de la méthode HTTP et de l’endpoint.
-* `description` : Le champ `description` de l’opération, s’il est présent.
-* `version` : La valeur `version` de l’ancre ou du Tab parent, si elle est présente.
-* `deprecated` : Le champ `deprecated` de l’opération. Si `true`, un libellé « obsolète » apparaîtra à côté du titre de l’endpoint dans la navigation latérale et sur la page de l’endpoint.
+* `title` : le champ `summary` de l’opération, s’il est présent. S’il n’y a pas de `summary`, le titre est généré à partir de la méthode HTTP et de l’endpoint.
+* `description` : le champ `description` de l’opération, s’il est présent.
+* `version` : la valeur `version` provenant de l’ancre parente ou du Tab, si présente.
+* `deprecated` : le champ `deprecated` de l’opération. Si `true`, un label « obsolète » apparaîtra à côté du titre de l’endpoint dans la navigation latérale et sur la page de l’endpoint.
- Pour exclure certains endpoints de vos pages d’API générées automatiquement, ajoutez la propriété
- [x-hidden](/fr/api-playground/customization/managing-page-visibility#x-hidden)
+ Pour exclure certains endpoints de vos pages d’API générées automatiquement, ajoutez la
+ propriété [x-hidden](/fr/api-playground/customization/managing-page-visibility#x-hidden)
à l’opération dans votre spécification OpenAPI.
-Deux approches permettent d’ajouter des pages d’endpoint à votre documentation :
+Il existe deux approches pour ajouter des pages d’endpoint à votre documentation :
-1. **Sections API dédiées** : Référencez des spécifications OpenAPI dans des éléments de navigation pour créer des sections API dédiées.
-2. **Endpoints ciblés** : Référencez des endpoints spécifiques dans votre navigation, aux côtés d’autres pages.
+1. **Sections d’API dédiées** : référencez des spécifications OpenAPI dans des éléments de navigation pour des sections d’API dédiées.
+2. **Endpoints ciblés** : référencez des endpoints spécifiques dans votre navigation, aux côtés d’autres pages.
- ### Sections API dédiées
+ ### Sections dédiées à l’API
-Générez des sections API dédiées en ajoutant un champ `openapi` à un élément de navigation, sans autres pages. Tous les endpoints de la spécification seront inclus :
+Générez des sections dédiées à l’API en ajoutant un champ `openapi` à un élément de navigation, sans inclure d’autres pages. Tous les endpoints de la spécification seront inclus :
```json {5}
"navigation": {
@@ -346,22 +348,20 @@ Vous pouvez utiliser plusieurs spécifications OpenAPI dans différentes section
```
- Le champ `directory` est facultatif et indique où les pages d’API générées sont
- stockées dans votre dépôt de documentation. S’il n’est pas précisé, la valeur par défaut est le répertoire `api-reference`
- de votre dépôt.
+ Le champ `directory` est facultatif et indique où sont stockées les pages d’API générées dans votre dépôt de documentation. S’il n’est pas renseigné, la valeur par défaut est le répertoire `api-reference` de votre dépôt.
- ### Endpoints ciblés
+ ### Points de terminaison sélectifs
-Lorsque vous souhaitez mieux contrôler l’emplacement des endpoints dans votre documentation, vous pouvez référencer des endpoints spécifiques dans votre navigation. Cette approche vous permet de générer des pages pour des endpoints d’API aux côtés d’autres contenus.
+Si vous souhaitez mieux contrôler l’endroit où les points de terminaison apparaissent dans votre documentation, vous pouvez référencer des points de terminaison spécifiques dans votre navigation. Cette approche vous permet de générer des pages pour des points de terminaison d’API aux côtés d’autres contenus.
#### Définir une spécification OpenAPI par défaut
-Configurez une spécification OpenAPI par défaut pour un élément de navigation, puis référencez des endpoints spécifiques dans le champ `pages` :
+Configurez une spécification OpenAPI par défaut pour un élément de navigation. Référencez ensuite des points de terminaison spécifiques dans le champ `pages` :
```json {12, 15-16}
"navigation": {
@@ -380,17 +380,17 @@ Configurez une spécification OpenAPI par défaut pour un élément de navigatio
"api-overview",
"GET /users",
"POST /users",
- "guides/authentication"
+ "guides/authentification"
]
}
]
}
```
-Toute entrée de page correspondant au format `METHOD /path` génèrera une page API pour cet endpoint en utilisant la spécification OpenAPI par défaut.
+Toute entrée de page correspondant au format `METHOD /path` générera une page d’API pour ce point de terminaison à partir de la spécification OpenAPI par défaut.
- #### Héritage de la spécification OpenAPI
+ #### Héritage des spécifications OpenAPI
Les spécifications OpenAPI sont héritées dans la hiérarchie de navigation. Les éléments de navigation enfants héritent de la spécification OpenAPI de leur parent, sauf s’ils définissent la leur :
@@ -426,28 +426,28 @@ Faites référence à des points de terminaison spécifiques sans définir de sp
"navigation": {
"pages": [
"introduction",
- "guides-utilisateur",
+ "user-guides",
"/path/to/openapi-v1.json POST /users",
"/path/to/openapi-v2.json GET /orders"
]
}
```
-Cette approche est utile lorsque vous avez besoin d’points de terminaison spécifiques provenant de différentes spécifications ou que vous souhaitez n’inclure que certains endpoints.
+Cette approche est utile lorsque vous avez besoin d’endpoints spécifiques issus de différentes spécifications ou que vous souhaitez n’inclure que certains endpoints.
- ## Créer des fichiers `MDX` pour les pages d’API
+ ## Créez des fichiers `MDX` pour les pages d’API
-Pour gérer chaque page d’endpoint individuellement, créez une page `MDX` par opération. Vous pouvez ainsi personnaliser les metadata de la page, ajouter du contenu, omettre certaines opérations ou réorganiser les pages dans la navigation au niveau de chaque page.
+Pour contrôler chaque page d’endpoint, créez une page `MDX` par opération. Vous pourrez ainsi personnaliser les metadata de la page, ajouter du contenu, omettre certaines opérations ou réorganiser les pages dans votre navigation au niveau de la page.
-Voir un [exemple de page MDX OpenAPI de MindsDB](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx?plain=1) et son rendu dans leur [documentation en ligne](https://docs.mindsdb.com/rest/databases/create-databases).
+Consultez un [exemple de page OpenAPI en MDX provenant de MindsDB](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx?plain=1) ainsi que son rendu dans leur [documentation en ligne](https://docs.mindsdb.com/rest/databases/create-databases).
### Spécifier les fichiers manuellement
-Créez une page `MDX` pour chaque endpoint et indiquez l’opération OpenAPI à afficher à l’aide du champ `openapi` dans le frontmatter.
+Créez une page MDX pour chaque endpoint et indiquez quelle opération OpenAPI afficher en utilisant le champ openapi dans le frontmatter.
Lorsque vous référencez une opération OpenAPI de cette manière, le nom, la description, les paramètres, les réponses et le bac à sable d’API sont générés automatiquement à partir de votre document OpenAPI.
@@ -455,15 +455,14 @@ Si vous avez plusieurs fichiers OpenAPI, incluez le chemin du fichier dans votre
Cette approche fonctionne que vous ayez ou non défini une spécification OpenAPI
- par défaut dans votre navigation. Vous pouvez référencer n’importe quel endpoint
- depuis n’importe quelle spécification OpenAPI en incluant le chemin du fichier
- dans le frontmatter.
+ par défaut dans votre navigation. Vous pouvez référencer n’importe quel endpoint depuis n’importe quelle spécification OpenAPI en
+ incluant le chemin du fichier dans le frontmatter.
-Si vous souhaitez référencer un fichier OpenAPI externe, ajoutez l’URL du fichier à votre `docs.json`.
+Si vous souhaitez référencer un fichier OpenAPI externe, ajoutez l’URL du fichier à votre docs.json.
- ```mdx Exemple
+ ```mdx Example
---
title: "Get users"
description: "Returns all plants from the system that the user has access to"
@@ -485,22 +484,22 @@ Si vous souhaitez référencer un fichier OpenAPI externe, ajoutez l’URL du fi
- La méthode et le chemin doivent correspondre exactement à la définition dans
- votre spécification OpenAPI. Si l’endpoint n’existe pas dans le fichier OpenAPI,
- la page sera vide.
+ La méthode et le chemin doivent correspondre exactement à la définition dans votre
+ spécification OpenAPI. Si l’endpoint n’existe pas dans le fichier OpenAPI, la page
+ sera vide.
### Générer automatiquement des fichiers `MDX`
-Utilisez notre [scraper](https://www.npmjs.com/package/@mintlify/scraping) Mintlify pour générer automatiquement des pages `MDX` pour les documents OpenAPI volumineux.
+Utilisez notre [scraper](https://www.npmjs.com/package/@mintlify/scraping) Mintlify pour générer automatiquement des pages `MDX` à partir de gros documents OpenAPI.
Votre document OpenAPI doit être valide, sinon les fichiers ne seront pas générés automatiquement.
-Le scraper génère :
+Le scraper génère :
* Une page `MDX` pour chaque opération dans le champ `paths` de votre document OpenAPI.
* Si votre document OpenAPI est en version 3.1+, une page `MDX` pour chaque opération dans le champ `webhooks` de votre document OpenAPI.
@@ -518,7 +517,7 @@ Le scraper génère :
npx @mintlify/scraping@latest openapi-file -o api-reference
```
- Ajoutez l’option `-o` pour spécifier un dossier dans lequel créer les fichiers. Si aucun dossier n’est spécifié, les fichiers seront créés dans le répertoire de travail.
+ Ajoutez l’option `-o` pour définir le dossier où créer les fichiers. Si aucun dossier n’est spécifié, les fichiers seront créés dans le répertoire de travail.
@@ -526,7 +525,7 @@ Le scraper génère :
### Créer des fichiers `MDX` pour les schémas OpenAPI
-Vous pouvez créer des pages individuelles pour tout schéma OpenAPI défini dans le champ `components.schema` d’un document OpenAPI :
+Vous pouvez créer des pages distinctes pour tout schéma OpenAPI défini dans le champ `components.schema` d’un document OpenAPI :
```mdx Exemple
@@ -542,22 +541,38 @@ Vous pouvez créer des pages individuelles pour tout schéma OpenAPI défini dan
```
+Si vous avez des schémas portant le même nom dans plusieurs fichiers, vous pouvez également préciser le fichier OpenAPI :
+
+
+ ```mdx Exemple
+ ---
+ openapi-schema: en-schema.json OrderItem
+ ---
+ ```
+
+ ```mdx Format
+ ---
+ openapi-schema: "path-to-schema-file schema-key"
+ ---
+ ```
+
+
## Webhooks
-Les webhooks sont des rappels (callbacks) HTTP que votre API envoie pour informer des systèmes externes lorsque des événements surviennent. Les webhooks sont pris en charge dans les documents OpenAPI 3.1+.
+Les webhooks sont des callbacks HTTP que votre API envoie pour notifier des systèmes externes lorsque des événements se produisent. Les webhooks sont pris en charge dans les documents OpenAPI 3.1+.
### Définir des webhooks dans votre spécification OpenAPI
-Ajoutez un champ `webhooks` à votre document OpenAPI, en complément du champ `paths`.
+Ajoutez un champ `webhooks` à votre document OpenAPI, en parallèle du champ `paths`.
Pour en savoir plus sur la définition des webhooks, consultez la section [Webhooks](https://spec.openapis.org/oas/v3.1.0#oasWebhooks) de la documentation OpenAPI.
- ### Référencer des webhooks dans des fichiers MDX
+ ### Référencer les webhooks dans les fichiers MDX
Lors de la création de pages MDX pour les webhooks, utilisez `webhook` plutôt que des méthodes HTTP comme `GET` ou `POST` :
diff --git a/zh/api-playground/openapi-setup.mdx b/zh/api-playground/openapi-setup.mdx
index abe552b19..da87bcece 100644
--- a/zh/api-playground/openapi-setup.mdx
+++ b/zh/api-playground/openapi-setup.mdx
@@ -4,13 +4,13 @@ description: "在文档页面中引用 OpenAPI 端点"
icon: "file-json"
---
-OpenAPI 是用于描述 API 的规范。Mintlify 支持 OpenAPI 3.0+ 文档，可生成交互式 API 文档并保持其为最新状态。
+OpenAPI 是用于描述 API 的规范。Mintlify 支持 OpenAPI 3.0+ 文档，可生成交互式 API 文档并保持其实时更新。
## 添加 OpenAPI 规范文件
-要使用 OpenAPI 为你的端点编写文档，你需要一份有效的 OpenAPI 文档，使用 JSON 或 YAML 格式，并遵循 [OpenAPI specification 3.0+](https://swagger.io/specification/)。
+要使用 OpenAPI 为你的端点编写文档，你需要一个有效的 OpenAPI 文档（JSON 或 YAML 格式），并符合 [OpenAPI 3.0+ 规范](https://swagger.io/specification/)。
你可以基于一个或多个 OpenAPI 文档创建 API 页面。
@@ -20,23 +20,22 @@ OpenAPI 是用于描述 API 的规范。Mintlify 支持 OpenAPI 3.0+ 文档，
我们推荐以下资源来学习并编写你的 OpenAPI 文档。
-* [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/v3_0/basic-structure/)：学习 OpenAPI 语法。
-* [The OpenAPI specification Markdown sources](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/)：参考最新版 OpenAPI 规范的详细信息。
-* [Swagger Editor](https://editor.swagger.io/)：用于编辑、验证和调试你的 OpenAPI 文档。
-* [The Mint CLI](https://www.npmjs.com/package/mint)：使用以下命令验证你的 OpenAPI 文档：`mint openapi-check
`。
+* [Swagger 的 OpenAPI 指南](https://swagger.io/docs/specification/v3_0/basic-structure/)，用于学习 OpenAPI 语法。
+* [OpenAPI 规范的 Markdown 源文件](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/)，用于查阅最新 OpenAPI 规范的详细信息。
+* [Swagger Editor](https://editor.swagger.io/)，用于编辑、验证和调试你的 OpenAPI 文档。
+* [Mint 命令行界面（CLI）](https://www.npmjs.com/package/mint)，可使用以下命令验证你的 OpenAPI 文档：`mint openapi-check `。
- Swagger's OpenAPI Guide 面向 OpenAPI v3.0，但几乎所有信息
- 都适用于 v3.1。关于 v3.0 与 v3.1 的差异，参见 OpenAPI 博客中的
- [Migrating from OpenAPI 3.0 to
- 3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0)。
+ Swagger 的 OpenAPI 指南面向 OpenAPI v3.0，但几乎所有信息
+ 都适用于 v3.1。关于 v3.0 与 v3.1 的差异，请参阅 OpenAPI 博客中的
+ [从 OpenAPI 3.0 迁移到 3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0)。
### 为你的 API 指定 URL
-要启用 Mintlify 的功能（例如 API 操作台），请在 OpenAPI 文档中添加 `servers` 字段，并设置 API 的基础 URL。
+要启用 Mintlify 的功能（例如 API 操作台），请在 OpenAPI 文档中添加一个 `servers` 字段，并填写你的 API 基础 URL。
```json
{
@@ -48,23 +47,23 @@ OpenAPI 是用于描述 API 的规范。Mintlify 支持 OpenAPI 3.0+ 文档，
}
```
-在 OpenAPI 文档中，不同的 API 端点通过其路径来区分，例如 `/users/{id}` 或简写为 `/`。基础 URL 用于确定这些路径应当附加到哪里。关于如何配置 `servers` 字段，请参阅 OpenAPI 文档中的 [API Server and Base Path](https://swagger.io/docs/specification/api-host-and-base-path/)。
+在 OpenAPI 文档中，不同的 API 端点通过其路径进行指定，例如 `/users/{id}` 或仅 `/`。基础 URL 定义了这些路径应附加到的位置。有关如何配置 `servers` 字段的更多信息，请参阅 OpenAPI 文档中的 [API Server and Base Path](https://swagger.io/docs/specification/api-host-and-base-path/)。
-API 操作台会使用这些服务器 URL 来确定请求的发送目标。如果你指定了多个服务器，将提供一个下拉菜单，方便用户在服务器之间切换。如果未指定服务器，API 操作台会使用简易模式，因为没有基础 URL 就无法发送请求。
+API 操作台会使用这些服务器 URL 来确定将请求发送到哪里。如果你指定了多个服务器，会提供一个下拉菜单，允许用户在服务器之间切换。如果你未指定服务器，由于缺少基础 URL 无法发送请求，API 操作台将使用简化模式。
-如果你的 API 在不同的 URL 下有端点，你可以针对特定路径或操作[覆盖 servers 字段](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers)。
+如果你的 API 在不同的 URL 上有端点，你可以为特定路径或操作[覆盖 servers 字段](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers)。
- ### 指定认证方式
+ ### 指定认证
-要在 API 文档和操作台中启用认证，请在 OpenAPI 文档中配置 `securitySchemes` 和 `security` 字段。API 说明与 API 操作台会基于 OpenAPI 文档中的安全配置自动添加认证字段。
+要在 API 文档和 API 操作台中启用认证，请在 OpenAPI 文档中配置 `securitySchemes` 和 `security` 字段。API 说明和 API 操作台会根据 OpenAPI 文档中的安全配置自动添加相应的认证字段。
添加 `securitySchemes` 字段以定义用户的认证方式。
- 以下示例展示了 Bearer 认证的配置。
+ 下面的示例展示了 Bearer 认证的配置：
```json
{
@@ -97,25 +96,25 @@ API 操作台会使用这些服务器 URL 来确定请求的发送目标。如
常见的认证类型包括：
-* [API Keys](https://swagger.io/docs/specification/authentication/api-keys/)：用于基于 header、query 或 cookie 的 key。
-* [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/)：用于 JWT（JSON Web Token）或 OAuth 令牌。
-* [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/)：用于用户名和密码。
+* [API Keys](https://swagger.io/docs/specification/authentication/api-keys/): 用于基于 header、query 或 cookie 的 key。
+* [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/): 用于 JWT（JSON Web Token）或 OAuth 令牌。
+* [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/): 用于用户名与密码。
-如果你的 API 中不同的端点需要不同的认证方式，可以针对特定的操作[覆盖 security 字段](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.)。
+如果 API 中不同端点需要不同的认证方式，你可以针对特定操作[覆盖 security 字段](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.)。
-有关定义和应用认证的更多信息，请参阅 OpenAPI 文档中的 [Authentication](https://swagger.io/docs/specification/authentication/)。
+有关定义与应用认证的更多信息，请参阅 OpenAPI 文档中的[Authentication](https://swagger.io/docs/specification/authentication/)。
## `x-mint` 扩展
-`x-mint` 是一个自定义的 OpenAPI 扩展，可对 API 文档的生成和展示进行更精细的控制。
+`x-mint` 扩展是一个自定义的 OpenAPI 扩展，用于对 API 文档的生成与展示方式提供更精细的控制。
- ### Metadata
+ ### 元数据
-在任意操作中添加 `x-mint: metadata`，即可覆盖生成的 API 页面默认 metadata。除 `openapi` 外，你可以使用任何在 `MDX` frontmatter 中有效的 metadata 字段：
+在任意操作中添加 `x-mint: metadata`，即可覆盖生成的 API 页面所使用的默认元数据。除 `openapi` 外，你可以使用在 `MDX` frontmatter 中有效的任何元数据字段：
```json {7-13}
{
@@ -146,7 +145,7 @@ API 操作台会使用这些服务器 URL 来确定请求的发送目标。如
### 内容
### Href
@@ -199,28 +198,28 @@ API 操作台会使用这些服务器 URL 来确定请求的发送目标。如
}
```
-当存在 `x-mint: href` 时，导航条目将直接指向指定的 URL，而不会生成 API 页面。
+当存在 `x-mint: href` 时，导航条目会直接指向指定的 URL，而不会生成 API 页面。
### MCP
-使用 `x-mint: mcp` 可选择性地将端点暴露为 Model Context Protocol（MCP）工具。仅启用在通过 AI 工具公开访问时依然安全的端点。
+使用 `x-mint: mcp` 有选择性地将端点公开为 Model Context Protocol（MCP）工具。仅启用可通过 AI 工具安全公开访问的端点。
该端点的 MCP 配置。
- 是否将该端点暴露为 MCP 工具。优先于文件级配置。
+ 是否将该端点公开为 MCP 工具。优先于文件级配置。
- MCP 工具的名称。
+ MCP 工具名称。
- MCP 工具的描述。
+ MCP 工具说明。
@@ -276,36 +275,36 @@ API 操作台会使用这些服务器 URL 来确定请求的发送目标。如
更多信息请参见 [Model Context Protocol](/zh/ai/model-context-protocol)。
- ## 自动填充 API 页面
+ ## 自动生成 API 页面
-在你的 `docs.json` 中为任意导航元素添加 `openapi` 字段，可自动为 OpenAPI 端点生成页面。你可以控制这些页面在导航结构中的位置，既可以作为独立的 API 分区，也可以与其他页面一起显示。
+在 `docs.json` 的任一导航元素中添加 `openapi` 字段，可自动为 OpenAPI 端点生成页面。你可以控制这些页面在导航结构中的位置，既可作为独立的 API 分区，也可与其他页面并列展示。
-`openapi` 字段可接受文档仓库中的文件路径，或指向已托管 OpenAPI 文档的 URL。
+`openapi` 字段可接受文档仓库中的文件路径，或指向托管 OpenAPI 文档的 URL。
-生成的端点页面具有以下默认 metadata 值：
+生成的端点页面默认包含以下 metadata 值：
-* `title`：若存在，则取该操作的 `summary` 字段；否则将根据 HTTP 方法和端点生成标题。
+* `title`：若存在，则取该操作的 `summary` 字段；否则根据 HTTP 方法和端点生成标题。
* `description`：若存在，则取该操作的 `description` 字段。
* `version`：若存在，则取父级锚点或 Tab 的 `version` 值。
-* `deprecated`：该操作的 `deprecated` 字段。若为 `true`，则会在侧边导航和端点页面的端点标题旁显示“已废弃”标签。
+* `deprecated`：取该操作的 `deprecated` 字段。若为 `true`，则会在侧边导航及端点页面的标题旁显示“已废弃”标签。
- 若要将特定端点从自动生成的 API 页面中排除，请在 OpenAPI 规范中该操作上添加
+ 若要将特定端点排除在自动生成的 API 页面之外，请在 OpenAPI 规范中该操作上添加
[x-hidden](/zh/api-playground/customization/managing-page-visibility#x-hidden)
属性。
-将端点页面添加到文档中的方法有两种：
+将端点页面加入文档有两种方式：
-1. 专用 API 分区：在导航元素中引用 OpenAPI 规范，作为独立的 API 分区。
-2. 选择性端点：在导航中与其他页面并列引用特定端点。
+1. 独立的 API 分区：在导航元素中引用 OpenAPI 规范，生成独立的 API 分区。
+2. 精选端点：在导航中与其他页面并列引用特定端点。
- ### 专用 API 分区
+ ### 专用 API 区块
-在导航元素中仅添加 `openapi` 字段且不包含其他页面，即可生成专用的 API 分区。规范中的所有端点都会被包含：
+在某个 navigation 元素中仅添加一个 `openapi` 字段（且不包含其他页面），即可生成专用的 API 区块。规范中的所有端点都会被包含：
```json {5}
"navigation": {
@@ -318,7 +317,7 @@ API 操作台会使用这些服务器 URL 来确定请求的发送目标。如
}
```
-您可以在导航的不同部分使用多个 OpenAPI 规范：
+你可以在不同的导航部分使用多个 OpenAPI 规范：
```json {8-11, 15-18}
"navigation": {
@@ -347,26 +346,26 @@ API 操作台会使用这些服务器 URL 来确定请求的发送目标。如
```
- `directory` 字段是可选的，用于指定在你的文档仓库中存放生成的 API 页面的位置。若未指定，则默认为仓库中的 `api-reference` 目录。
+ `directory` 字段为可选，用于指定在文档仓库中保存生成的 API 页面的路径。若未指定，则默认使用仓库中的 `api-reference` 目录。
### 选择性端点
-当你希望更精细地控制端点在文档中的展示位置时，可以在导航中引用特定端点。此方法可让你在其他内容旁边生成这些 API 端点的页面。
+当你希望更精确地控制端点在文档中的显示位置时，可以在导航中引用特定端点。此方法允许你在其他内容旁边生成这些 API 端点的页面。
- #### 设置默认 OpenAPI 规范
+ #### 设定默认 OpenAPI 规范
-为某个导航元素配置默认的 OpenAPI 规范，然后在 `pages` 字段中引用特定端点：
+为某个导航元素配置默认的 OpenAPI 规范，然后在 `pages` 字段中引用具体的端点：
```json {12, 15-16}
"navigation": {
"tabs": [
{
- "tab": "入门指南",
+ "tab": "快速入门",
"pages": [
"quickstart",
"installation"
@@ -386,13 +385,13 @@ API 操作台会使用这些服务器 URL 来确定请求的发送目标。如
}
```
-任何符合 `METHOD /path` 格式的页面条目都会使用默认的 OpenAPI 规范为该端点生成一个 API 页面。
+任何符合 `METHOD /path` 格式的页面条目都会使用默认的 OpenAPI 规范为该端点生成 API 页面。
#### OpenAPI 规范继承
-OpenAPI 规范会沿着导航层级向下继承。子级导航元素会继承其父级的 OpenAPI 规范，除非它们定义了自己的规范：
+OpenAPI 规范会沿着导航层级向下继承。子级导航元素将继承其父级的 OpenAPI 规范，除非它们定义了自己的规范：
```json {3, 7-8, 11, 13-14}
{
@@ -419,7 +418,7 @@ OpenAPI 规范会沿着导航层级向下继承。子级导航元素会继承其
#### 单个端点
### 手动指定文件
@@ -448,43 +447,43 @@ OpenAPI 规范会沿着导航层级向下继承。子级导航元素会继承其
为每个端点创建一个 `MDX` 页面，并在 frontmatter 中使用 `openapi` 字段指定要展示的 OpenAPI 操作。
-以这种方式引用 OpenAPI 操作时，名称、说明、参数、响应以及 API 操作台会根据你的 OpenAPI 文档自动生成。
+以这种方式引用 OpenAPI 操作时，名称、说明、参数、响应以及 API 操作台都会根据你的 OpenAPI 文档自动生成。
-如果你有多个 OpenAPI 文件，请在引用中包含文件路径，以确保 Mintlify 能找到正确的 OpenAPI 文档。若只有一个 OpenAPI 文件，Mintlify 将自动检测。
+如果你有多个 OpenAPI 文件，请在引用中包含文件路径，以确保 Mintlify 能找到正确的 OpenAPI 文档；如果只有一个 OpenAPI 文件，Mintlify 会自动检测到它。
无论你是否在导航中设置了默认 OpenAPI 规范，此方法都适用。
- 你可以通过在 frontmatter 中包含文件路径，引用任何 OpenAPI
- 规范中的任意端点。
+ 你可以通过在 frontmatter 中包含文件路径，从任何 OpenAPI 规范中
+ 引用任意端点。
-如果你想引用外部 OpenAPI 文件，请将该文件的 URL 添加到你的 `docs.json` 中。
+如果你想引用外部的 OpenAPI 文件，请将该文件的 URL 添加到你的 `docs.json` 中。
- ```mdx 示例
+ ```mdx Example
---
title: "Get users"
- description: "返回用户可访问的系统中所有植物"
+ description: "Returns all plants from the system that the user has access to"
openapi: "/path/to/openapi-1.json GET /users"
deprecated: true
version: "1.0"
---
```
- ```mdx 格式
+ ```mdx Format
---
- title: "页面标题"
- description: "页面说明"
+ title: "title of the page"
+ description: "description of the page"
openapi: openapi-file-path method path
- deprecated: boolean (非必填)
- version: "version-string" (非必填)
+ deprecated: boolean (not required)
+ version: "version-string" (not required)
---
```
- method 和 path 必须与 OpenAPI 规范中的定义完全匹配。
- 如果该端点在 OpenAPI 文件中不存在，页面将为空。
+ 方法和路径必须与 OpenAPI 规范中的定义完全一致。
+ 如果该端点在 OpenAPI 文件中不存在，页面内容将为空。
@@ -494,13 +493,13 @@ OpenAPI 规范会沿着导航层级向下继承。子级导航元素会继承其
使用我们的 Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) 为大型 OpenAPI 文档自动生成 `MDX` 页面。
- 你的 OpenAPI 文档必须有效，否则文件将无法自动生成。
+ 你的 OpenAPI 文档必须有效，否则将无法自动生成文件。
-该 scraper 会生成：
+scraper 将生成：
-* 针对 OpenAPI 文档中 `paths` 字段的每个操作生成一个 `MDX` 页面。
-* 如果你的 OpenAPI 文档是 3.1+ 版本，则会针对文档中 `webhooks` 字段的每个操作生成一个 `MDX` 页面。
+* 针对你的 OpenAPI 文档中 `paths` 字段的每个操作生成一个 `MDX` 页面。
+* 如果你的 OpenAPI 文档为 3.1+ 版本，针对 `webhooks` 字段中的每个操作生成一个 `MDX` 页面。
* 一组可添加到 `docs.json` 的 navigation 条目数组。
@@ -515,15 +514,15 @@ OpenAPI 规范会沿着导航层级向下继承。子级导航元素会继承其
npx @mintlify/scraping@latest openapi-file -o api-reference
```
- 添加 `-o` 标志以指定输出文件夹。若未指定文件夹，文件将生成在当前工作目录中。
+ 添加 `-o` 标志以指定生成文件的输出文件夹。未指定时，文件将生成到当前工作目录。
- ### 为 OpenAPI 模式创建 `MDX` 文件
+ ### 为 OpenAPI 架构创建 `MDX` 文件
-你可以为 OpenAPI 文档的 `components.schema` 字段中定义的任意 OpenAPI 模式创建独立页面：
+你可以为 OpenAPI 文档的 `components.schema` 字段中定义的任意 OpenAPI 架构创建独立页面：
```mdx 示例
@@ -539,25 +538,41 @@ OpenAPI 规范会沿着导航层级向下继承。子级导航元素会继承其
```
+如果你在多个文件中有同名的架构，也可以同时指定 OpenAPI 文件：
+
+
+ ```mdx 示例
+ ---
+ openapi-schema: en-schema.json OrderItem
+ ---
+ ```
+
+ ```mdx 格式
+ ---
+ openapi-schema: "path-to-schema-file schema-key"
+ ---
+ ```
+
+
## Webhooks
-Webhooks 是当事件发生时，你的 API 用于通知外部系统的 HTTP 回调。OpenAPI 3.1 及以上版本的文档支持 Webhooks。
+Webhook 是你的 API 在事件发生时发送的 HTTP 回调，用于通知外部系统。OpenAPI 3.1+ 文档支持 Webhook。
### 在 OpenAPI 规范中定义 webhooks
-在 OpenAPI 文档中与 `paths` 字段并列添加 `webhooks` 字段。
+在 OpenAPI 文档中添加一个 `webhooks` 字段，与 `paths` 字段并列。
-有关定义 webhooks 的更多信息，请参阅 OpenAPI 文档中的 [Webhooks](https://spec.openapis.org/oas/v3.1.0#oasWebhooks)。
+有关如何定义 webhooks 的更多信息，请参阅 OpenAPI 文档中的 [Webhooks](https://spec.openapis.org/oas/v3.1.0#oasWebhooks)。
### 在 MDX 文件中引用 webhooks
-为 webhooks 创建 MDX 页面时，使用 `webhook`，而不是 `GET` 或 `POST` 等 HTTP 方法：
+为 webhooks 创建 MDX 页面时，请使用 `webhook`，而不是 `GET` 或 `POST` 等 HTTP 方法：
```mdx
---