Ajouter des exemples de SDK

Ajoutez des exemples de code SDK à votre documentation d'API avec l'extension OpenAPI x-codeSamples ou automatiquement avec Speakeasy.

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.

Ajouter des exemples manuellement

Ajoutez la propriété x-codeSamples à n’importe quelle méthode de requête. Elle suit le schéma suivant.

langstringrequired

Le langage de l’exemple de code.

labelstring

Le libellé de l’exemple. Utile lorsque vous fournissez plusieurs exemples pour un même endpoint.

sourcestringrequired

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.

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 });

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.

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.

Capture d'écran montrant l'entrée du registre de la spécification combinée avec la fonction de copie d'URL mise en évidence par un carré rouge.

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.

{
  "navigation": {
    "anchors": [
      {
        "anchor": "API reference",
        "icon": "square-terminal",
        // !mark
        "openapi": "SPEAKEASY_COMBINED_SPEC_URL"
      }
    ]
  }
}

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.

Ajouter des exemples de SDK

Ajouter des exemples manuellement

Générer des exemples avec Speakeasy

On this page