Passer au contenu principal
Utilisez la propriété de navigation sdk pour générer des pages de référence pour vos bibliothèques SDK à partir des outils de documentation que vous exécutez déjà. Mintlify lit l’artefact de build de chaque outil et crée une page pour chaque classe, interface, module et fonction. Les groupes de navigation, les liens entre les pages et l’indexation pour la recherche sont également inclus.

​
Formats pris en charge

​
Générer un artefact

Exécutez votre outil de documentation avec un format de sortie lisible par machine. Si vous publiez déjà de la documentation générée depuis votre CI, il s’agit généralement de l’ajout d’un seul flag à la même commande.

​
Go

Les outils de documentation de Go produisent du texte et du HTML, pas un artefact lisible par une machine. Mintlify maintient donc mintlify-go-extractor, une commande open source qui en génère un. Exécutez-la depuis n’importe quel emplacement de votre module Go. Elle lit les fichiers source de votre module avec la bibliothèque standard de Go : elle ne télécharge aucune dépendance, n’a besoin d’aucun identifiant et fonctionne avec les modules privés. Avec Go 1.24 ou une version ultérieure, épinglez l’extracteur dans le go.mod de votre module pour que chaque exécution utilise la même version :
Chaque version inclut des binaires précompilés pour macOS, Linux et Windows. Par défaut, l’extracteur documente tous les packages du module, à l’exception des packages internal et des commandes, et lit les commentaires de documentation comme du Markdown, ce qu’écrivent les SDK générés (par exemple avec Stainless, Speakeasy ou Fern). Options courantes :
  • -comments=godoc : lit les commentaires de documentation avec la syntaxe des commentaires de documentation de Go plutôt qu’en Markdown.
  • -exclude : ignore des packages, sous la forme d’une liste de motifs de package séparés par des virgules.
  • -goos, -goarch, -tags : choisissent la plateforme et les tags de build utilisés pour sélectionner les fichiers. La valeur par défaut est linux/amd64.
Passez des motifs de package, comme ./option/..., pour ne documenter qu’une partie du module. Consultez le README de l’extracteur pour la liste complète des options.

​
Remplir automatiquement les pages SDK

Ajoutez une propriété sdk à un onglet ou à un groupe dans votre docs.json. Mintlify analyse l’artefact et crée des groupes de navigation et des pages pour la bibliothèque.
Ajoutez sdk à un groupe pour générer des pages dans une section d’un onglet plutôt que dans l’onglet entier. Les groupes et pages héritent des paramètres sdk de l’onglet ou du groupe parent. Si un groupe imbriqué définit son propre sdk, Mintlify utilise ces paramètres à la place de ceux hérités.
Un groupe avec sdk peut aussi lister des pages que vous rédigez vous-même. Vos pages apparaissent en premier, suivies des groupes de référence générés.
Vous pouvez déclarer sdk sur un onglet ou un groupe.
  • Un onglet avec sdk peut inclure des groups, mais aucune autre structure de navigation, telle que pages, versions ou languages. Il ne peut pas non plus inclure une propriété openapi, asyncapi ou graphql.
  • Un groupe avec sdk peut inclure des pages et des groupes imbriqués, mais ne peut pas inclure une propriété graphql.
​
string
requis
L’outil de documentation qui a produit l’artefact : typedoc, docfx, javadoc, sphinx, phpdoc ou go.
​
string
requis
Chemin relatif vers le fichier ou le répertoire de l’artefact dans votre dépôt de documentation, ou une URL HTTPS. Les URL HTTP ne sont pas acceptées.
​
string
Le préfixe du chemin d’URL pour les pages générées. Par défaut, sdk-reference.
Ajoutez plusieurs onglets ou groupes pour documenter plusieurs bibliothèques. Par exemple, utilisez deux groupes dans le même onglet pour les versions stable et bêta d’un SDK. Utilisez un directory unique pour chaque bibliothèque afin d’éviter les collisions de routes.
Ajoutez le répertoire de votre artefact à .mintignore afin que Mintlify traite les artefacts comme des entrées de build plutôt que de les publier comme des ressources statiques.

​
Pages générées

Mintlify ajoute les groupes de navigation générés après les éventuels groups de l’onglet. Si vous ajoutez sdk à un groupe, les groupes générés apparaissent après les pages de ce groupe. Les groupes varient selon le format et peuvent représenter des modules, des packages, des espaces de noms ou des types de symboles. Pour les artefacts TypeDoc, Mintlify suit l’organisation que vous définissez avec les balises @category et @group. Les catégories et les titres de groupe personnalisés deviennent des groupes de navigation. Les catégories à l’intérieur d’un groupe deviennent des groupes imbriqués, et les espaces de noms deviennent des groupes imbriqués qui suivent leurs propres catégories ou groupes. Si l’artefact ne contient ni catégories ni titres de groupe personnalisés, Mintlify regroupe les pages par type de symbole, comme les classes, les interfaces et les fonctions. Pour les artefacts Javadoc, Mintlify regroupe les pages par package. Lorsqu’un package mélange plusieurs genres, il les imbrique sous Interfaces, Classes, Enums, Records, Exceptions, Errors et Annotations, dans l’ordre utilisé par Javadoc sur ses pages de package. Pour les artefacts Go, Mintlify regroupe les pages par package. Chaque package commence par une page de présentation qui affiche le README et le commentaire de documentation du package, suivie d’un index de ses types et fonctions. Chaque type et chaque fonction au niveau du package dispose de sa propre page. La page d’un type comprend ses champs, ses constructeurs et ses méthodes. Chaque page générée documente une classe, une interface, une fonction, un type ou un autre symbole de l’artefact et renvoie vers les pages générées associées. Si un convertisseur produit des pages qui n’appartiennent à aucun groupe, Mintlify les regroupe sous un groupe Reference.

​
Personnaliser une page pour un seul symbole

Utilisez le frontmatter sdk sur une page MDX pour cibler un seul symbole de l’artefact. Mintlify affiche le contenu que vous rédigez, puis ajoute la référence générée pour ce symbole en dessous. Utilisez cette approche lorsque vous souhaitez ajouter des exemples, des notes de migration ou du contexte au-dessus d’une classe, d’une interface ou d’une méthode spécifique. Ajoutez la page à la navigation de votre docs.json, comme n’importe quelle autre page. Mintlify ne génère du contenu SDK que pour les pages qui apparaissent dans votre navigation. Dès qu’un onglet ou un groupe avec sdk contient une page avec un frontmatter sdk, Mintlify cesse de remplir automatiquement cet onglet ou ce groupe et n’affiche que les pages que vous avez rédigées. Déplacez la page hors de l’onglet ou du groupe si vous souhaitez que le reste de la bibliothèque soit rempli automatiquement. Pointez sdk vers un symbole :
La forme chaîne suit le modèle [source] kind name. Si vous omettez source, la page l’hérite de la configuration sdk de l’onglet ou du groupe. La forme chaîne hérite toujours de format et ne fonctionne donc que sur les pages situées sous un onglet ou un groupe avec sdk. Dans tous les autres cas, définissez sdk comme un objet avec les champs ci-dessous. Pour les méthodes et propriétés, incluez le nom du parent, par exemple method Client.getUser. Pour les artefacts Go, ciblez les structs et les autres types définis avec type, les interfaces avec interface, les champs de struct avec property et les pages de présentation de package avec package. Désignez un package par son nom, suivi du chemin de son répertoire pour les packages imbriqués, par exemple package openai ou package openai.option. Ajoutez le package au nom d’un symbole, par exemple type option.RequestOption, lorsque plusieurs packages ont un symbole portant ce nom. Si vous omettez title ou description, Mintlify utilise le titre et la description générés pour le symbole.
​
string
requis
Le type de symbole : package, class, interface, enum, function, type, variable, method ou property.
​
string
requis
Le nom du symbole tel qu’il apparaît dans l’artefact.
​
string
Requis pour les cibles method et property. La classe, l’interface ou le type englobant.
​
string
Pour les artefacts Go, le package qui contient le symbole, par exemple openai.option. Utilisez-le lorsque plusieurs packages ont un symbole portant le même nom.
​
string
Remplace le format hérité. Requis lorsque la page ne se trouve pas sous un onglet ou un groupe avec sdk. Disponible uniquement dans la forme objet.
​
string
Remplace le source hérité. Requis lorsque la page ne se trouve pas sous un onglet ou un groupe avec sdk.

​
Utiliser des sources distantes

Définissez source sur une URL HTTPS pour récupérer l’artefact au moment du build au lieu de le committer dans votre dépôt de documentation. Les formats à fichier unique (typedoc, phpdoc, go) acceptent une URL de fichier directe. Les formats à répertoire (docfx, javadoc, sphinx) acceptent une archive zip. Les jars Javadoc publiés sur Maven Central fonctionnent sans reconditionnement :
Les artefacts distants ont une limite de téléchargement de 50 Mo et une limite de taille extraite de 200 Mo.

​
Maintenir les références à jour

Régénérez l’artefact chaque fois que votre SDK change. Un modèle courant consiste à configurer un job CI dans chaque dépôt de SDK. Ce job exécute l’outil de documentation à chaque publication, puis commite l’artefact dans votre dépôt de documentation ou le téléverse vers une URL stable référencée par source.

​
Configuration du dépôt

Stockez le code de votre SDK et votre documentation dans le même dépôt ou dans des dépôts séparés. Choisissez le modèle qui correspond à votre configuration. Les deux options offrent les mêmes fonctionnalités.

​
SDK et documentation dans le même dépôt

Générez l’artefact de votre SDK dans le même dépôt que votre documentation et indiquez son chemin relatif dans source. Tout workflow qui produit déjà l’artefact lors d’un push ou d’une publication peut le commiter dans le dépôt, puis publier les mises à jour lors du prochain déploiement du site de documentation.

​
SDK dans un dépôt séparé

Lorsque le SDK se trouve dans son propre dépôt, vous avez deux options.
  1. Commiter l’artefact dans votre dépôt de documentation. Dans le dépôt du SDK, exécutez un job CI lors d’une publication pour générer l’artefact et ouvrir une pull request (ou pousser un commit) vers votre dépôt de documentation avec le fichier mis à jour. Fusionnez cette modification dans votre branche de déploiement pour déclencher un déploiement du site. Définissez source sur le chemin commité, comme pour la configuration avec un seul dépôt.
  2. Héberger l’artefact et le récupérer au moment du build. Téléversez l’artefact vers une URL HTTPS stable. Par exemple, un bucket S3, un asset GitHub Releases ou Maven Central pour des jars Javadoc. Définissez source sur l’URL. Déclenchez un déploiement du site de documentation pour récupérer le nouvel artefact chaque fois que vous le mettez à jour. Appelez l’endpoint Déclencher un déploiement depuis le pipeline de publication de votre SDK après avoir publié l’artefact.
Si vos publications sont peu fréquentes ou si vous souhaitez que le dépôt de documentation soit la source de vérité, commitez l’artefact dans votre dépôt de documentation. Si vos publications sont fréquentes, que les artefacts sont volumineux ou que vous les publiez déjà (par exemple, des jars Javadoc sur Maven Central), hébergez l’artefact et récupérez-le au moment du build.