Passer au contenu principal
Chaque page d’endpoint affiche des exemples de code de requête à côté du playground. Par défaut, Mintlify les génère à partir de votre spécification OpenAPI dans les langages que vous choisissez. Si vos utilisateurs appellent votre API via un SDK ou une CLI, ajoutez vos propres exemples avec l’extension x-codeSamples, ou récupérez-les depuis Speakeasy.

Choisir les langages des exemples

Définissez api.examples.languages dans votre docs.json pour choisir les langages qui apparaissent dans les exemples générés. Les langages s’affichent dans l’ordre où vous les listez.
docs.json
Définissez defaults sur required pour exclure les paramètres facultatifs des exemples générés. La valeur par défaut, all, les inclut.
Pour n’afficher que les exemples que vous écrivez, définissez api.examples.autogenerate sur false. Les pages d’endpoint affichent alors uniquement les x-codeSamples de votre spécification, ou les composants <RequestExample> sur les pages MDX.

Écrire vos propres exemples

Ajoutez la propriété x-codeSamples à n’importe quelle opération. Elle suit le schéma suivant.
string
requis
Le langage de l’exemple de code.
string
Le libellé de l’exemple. Utile lorsque vous fournissez plusieurs exemples pour un même endpoint.
string
requis
Le code source de l’exemple.
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.

Générer des exemples avec Speakeasy

Si vous générez vos SDK avec Speakeasy, 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 à côté de vos endpoints.
1

Récupérez l'URL de la spécification combinée depuis le registre

Accédez à votre tableau de bord Speakeasy et ouvrez l’onglet API Registry. Ouvrez l’entrée *-with-code-samples de votre API.
Capture d'écran de la page API Registry de Speakeasy. Un carré rouge et le chiffre 1 mettent en évidence l'onglet API Registry, et un carré rouge et le chiffre 2 mettent en évidence l'entrée de l'API.
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 configurée.
Depuis la page de l’entrée du registre, copiez l’URL publique fournie.
2

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.
3

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 configurée et d’au moins une cible de SDK activée.