Exemple OpenAPI

Cette page présente un endpoint en direct généré à partir d'une spécification OpenAPI. Le schéma de requête, les modèles de réponse et les exemples de code du panneau de droite sont tous générés automatiquement à partir de la spec, sans rédaction manuelle.

Ce qui est généré

À partir d'une seule ligne de frontmatter openapi, Jamdesk génère automatiquement :

• Un badge d'endpoint affichant la méthode et le chemin avec un code couleur
• Une documentation des paramètres pour les paramètres de chemin, de requête, d'en-tête et de corps
• Des schémas de requête et de réponse, y compris les objets imbriqués et les tableaux
• Des exemples de code en cURL, Python, JavaScript, Go, Ruby, C#, Java, Rust et PHP (configurable via api.examples.languages)
• Des détails d'authentification extraits des schémas de sécurité de la spec

Toutes les références $ref de votre spec sont résolues automatiquement, vous pouvez donc organiser les schémas avec components/schemas comme d'habitude.

Les descriptions de votre spec sont rendues en Markdown, et non affichées en texte brut — les descriptions d'opération, de paramètre, de corps de requête, de réponse et de schéma prennent toutes en charge le même gras, code, listes, liens et tableaux GFM que vous écririez dans une page .mdx.

Configurer OpenAPI

Placez votre spec OpenAPI 3.x (YAML ou JSON) dans le répertoire openapi/, enregistrez-la dans docs.json sous api.openapi, puis ajoutez openapi: /openapi/your-spec.yaml METHOD /path au frontmatter de n'importe quelle page. Consultez le guide de configuration OpenAPI pour tous les détails.

Générer une page pour chaque opération

Plutôt que de rédiger une page par endpoint, pointez un onglet de navigation vers la spec et laissez Jamdesk construire toute la référence :

{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": { "source": "/openapi/api.yaml", "generate": true }
      }
    ]
  }
}

Chaque opération obtient une page et la barre latérale est regroupée par tag. Les fichiers .mdx déjà commités dans le dépôt sont prioritaires en cas de collision de slug, vous pouvez donc adopter cette approche une page à la fois, et renommer un chemin dans votre spec redirige l'ancienne URL au lieu de la casser. Consultez navigation openapi pour toutes les règles et les limites actuelles.

Pages associées