Ajouter des exemples de SDK

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 ou, si vous générez vos SDK avec Speakeasy, les faire ajouter automatiquement à 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.

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.

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 l’API.

Si l’entrée n’est pas étiquetée Combined Spec, vérifiez que l’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.

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"
      }
    ]
  }
}

{
  "navigation": {
    "tabs": [
      {
        "tab": "API reference",
        // !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.

Prise en main

Créer du contenu

Gérer votre site

Agent

Assistant

Contenu adapté aux agents

Recherche et SEO

Documenter des API

Intégrations

Référence

Ajouter des exemples de SDK

Ajouter des exemples manuellement

Générer des exemples avec Speakeasy

​Ajouter des exemples manuellement

​Générer des exemples avec Speakeasy

Ajouter des exemples manuellement

Générer des exemples avec Speakeasy