mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
b34afc88b6
* docs: fix es/fr/zh translation lag and add missing zh workflows redirects * docs: SEO metadata fixes and HTML entity cleanup in touched locale pages --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
130 lines
4.9 KiB
Plaintext
130 lines
4.9 KiB
Plaintext
---
|
|
title: "Ajouter des exemples de SDK"
|
|
description: "Ajoutez des exemples de code SDK à votre documentation d'API avec l'extension OpenAPI x-codeSamples ou automatiquement avec Speakeasy."
|
|
keywords: ["x-codeSamples", "exemples de SDK", "Speakeasy", "SDK autogénérés"]
|
|
---
|
|
|
|
Si vos utilisateurs interagissent avec votre API via un SDK plutôt que par des requêtes réseau directes, ajoutez des exemples de code SDK avec l'extension `x-codeSamples`. Mintlify affiche ces exemples sur vos pages OpenAPI.
|
|
|
|
Vous pouvez écrire ces exemples vous-même. Si vous générez vos SDK avec Speakeasy, Speakeasy peut ajouter automatiquement les exemples à votre spécification.
|
|
|
|
<div id="add-examples-manually">
|
|
## Ajouter des exemples manuellement
|
|
</div>
|
|
|
|
Ajoutez la propriété `x-codeSamples` à n'importe quelle méthode de requête. Elle suit le schéma suivant.
|
|
|
|
<ParamField body="lang" type="string" required>
|
|
Le langage de l'exemple de code.
|
|
</ParamField>
|
|
|
|
<ParamField body="label" type="string">
|
|
Le libellé de l'exemple. Utile lorsque vous fournissez plusieurs exemples pour un même endpoint.
|
|
</ParamField>
|
|
|
|
<ParamField body="source" type="string" required>
|
|
Le code source de l'exemple.
|
|
</ParamField>
|
|
|
|
L'exemple suivant montre des exemples de code pour une application de suivi de plantes qui dispose à la fois d'un outil CLI Bash et d'un SDK JavaScript.
|
|
|
|
```yaml
|
|
paths:
|
|
/plants:
|
|
get:
|
|
# ...
|
|
x-codeSamples:
|
|
- lang: bash
|
|
label: List all unwatered plants
|
|
source: |
|
|
planter list -u
|
|
- lang: javascript
|
|
label: List all unwatered plants
|
|
source: |
|
|
const planter = require('planter');
|
|
planter.list({ unwatered: true });
|
|
- lang: bash
|
|
label: List all potted plants
|
|
source: |
|
|
planter list -p
|
|
- lang: javascript
|
|
label: List all potted plants
|
|
source: |
|
|
const planter = require('planter');
|
|
planter.list({ potted: true });
|
|
```
|
|
|
|
<div id="generate-examples-with-speakeasy">
|
|
## Générer des exemples avec Speakeasy
|
|
</div>
|
|
|
|
Si vous générez vos SDK avec [Speakeasy](https://www.speakeasy.com), vous pouvez intégrer ses extraits autogénérés dans votre référence d'API au lieu de les maintenir manuellement. Les extraits apparaissent dans le [playground interactif](/fr/api-playground/overview) à côté de vos endpoints.
|
|
|
|
<Steps>
|
|
<Step title="Récupérez l'URL de la spécification combinée depuis le registre">
|
|
|
|
Accédez à votre [tableau de bord Speakeasy](https://app.speakeasy.com) et ouvrez l'onglet **API Registry**. Ouvrez l'entrée `*-with-code-samples` de votre API.
|
|
|
|
<Frame>
|
|
|
|
</Frame>
|
|
|
|
<Note>
|
|
Si l'entrée n'est pas étiquetée **Combined Spec**, vérifiez que votre API dispose d'une [URL d'exemples de code automatiques](https://www.speakeasy.com/docs/code-samples/automated-code-sample-urls) configurée.
|
|
</Note>
|
|
|
|
Depuis la page de l'entrée du registre, copiez l'URL publique fournie.
|
|
|
|
<Frame>
|
|
|
|
</Frame>
|
|
</Step>
|
|
<Step title="Ajoutez l'URL de la spécification combinée à votre fichier `docs.json`">
|
|
|
|
Ajoutez l'URL de la spécification combinée à une ancre ou à un onglet dans l'objet `navigation` de votre fichier `docs.json`.
|
|
|
|
<CodeGroup>
|
|
|
|
```json title="Anchor"
|
|
{
|
|
"navigation": {
|
|
"anchors": [
|
|
{
|
|
"anchor": "API reference",
|
|
"icon": "square-terminal",
|
|
// !mark
|
|
"openapi": "SPEAKEASY_COMBINED_SPEC_URL"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
```json title="Tab"
|
|
{
|
|
"navigation": {
|
|
"tabs": [
|
|
{
|
|
"tab": "API reference",
|
|
// !mark
|
|
"openapi": "SPEAKEASY_COMBINED_SPEC_URL"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
</CodeGroup>
|
|
</Step>
|
|
<Step title="Vérifiez l'intégration">
|
|
|
|
Après avoir redéployé votre documentation, ouvrez n'importe quel endpoint dans votre référence d'API et confirmez que les extraits par langage apparaissent dans le playground. L'ensemble des langages disponibles correspond aux cibles de SDK configurées dans votre projet Speakeasy.
|
|
|
|
Si les extraits n'apparaissent pas, vérifiez que :
|
|
|
|
- L'URL `openapi` dans `docs.json` pointe vers l'entrée de spécification combinée `*-with-code-samples`, et non vers le fichier OpenAPI source.
|
|
- L'URL de la spécification combinée est accessible publiquement depuis le navigateur.
|
|
- Votre projet Speakeasy dispose d'une [URL d'exemples de code automatisés](https://www.speakeasy.com/docs/code-samples/automated-code-sample-urls) configurée et d'au moins une cible de SDK activée.
|
|
|
|
</Step>
|
|
</Steps>
|