mintlify__docs/fr/api-playground/sdk-reference-setup.mdx

---
title: "Configuration des références SDK"
description: "Générez des pages de référence SDK à partir de votre outillage de documentation existant : TypeDoc, DocFX, Javadoc, Sphinx ou phpDocumentor."
keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "reference"]
---

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.

<div id="supported-formats">
  ## Formats pris en charge
</div>

| `format` | Outil | Artefact |
| --- | --- | --- |
| `typedoc` | [TypeDoc](https://typedoc.org) (TypeScript/JavaScript) | Fichier d’export JSON |
| `docfx` | [DocFX](https://dotnet.github.io/docfx/) (.NET) | Répertoire de sortie de `docfx metadata` (YAML ManagedReference) |
| `javadoc` | [Javadoc](https://docs.oracle.com/en/java/javase/17/javadoc/javadoc.html) (Java) | Répertoire HTML du doclet standard |
| `sphinx` | [Sphinx](https://www.sphinx-doc.org) (Python) | Répertoire de sortie du builder JSON |
| `phpdoc` | [phpDocumentor](https://phpdoc.org) (PHP) | Fichier `structure.xml` |

<div id="generate-an-artifact">
  ## Générer un artefact
</div>

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.

<CodeGroup>

```bash TypeDoc
npx typedoc --json typedoc.json src/index.ts
```

```bash DocFX
docfx metadata docfx.json
```

```bash Javadoc
javadoc -d javadoc-output -sourcepath src/main/java -subpackages com.example
# Ou téléchargez le jar javadoc publié depuis Maven Central
```

```bash Sphinx
python -m sphinx -b json docs/source artifacts/json
```

```bash phpDocumentor
phpdoc -d src -t artifacts --template=xml
```

</CodeGroup>

<div id="auto-populate-sdk-pages">
  ## Remplir automatiquement les pages SDK
</div>

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.

```json
"navigation": {
  "tabs": [
    {
      "tab": "SDK Reference",
      "sdk": {
        "format": "typedoc",
        "source": "sdk-artifacts/typedoc.json",
        "directory": "sdk/typescript"
      }
    }
  ]
}
```

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.

```json
{
  "group": "TypeScript SDK",
  "sdk": {
    "format": "typedoc",
    "source": "sdk-artifacts/typedoc.json",
    "directory": "sdk/typescript"
  },
  "pages": ["sdk/typescript/overview"]
}
```

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.

<Note>
  Vous pouvez déclarer `sdk` sur un [onglet](/fr/organize/navigation#tabs) ou un [groupe](/fr/organize/navigation#groups).

  - 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`.
</Note>

<ParamField path="format" type="string" required>
  L’outil de documentation qui a produit l’artefact : `typedoc`, `docfx`, `javadoc`, `sphinx` ou `phpdoc`.
</ParamField>

<ParamField path="source" type="string" required>
  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.
</ParamField>

<ParamField path="directory" type="string">
  Le préfixe du chemin d’URL pour les pages générées. Par défaut, `sdk-reference`.
</ParamField>

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.

<Tip>
  Ajoutez le répertoire de votre artefact à [`.mintignore`](/fr/organize/mintignore) afin que Mintlify traite les artefacts comme des entrées de build plutôt que de les publier comme des ressources statiques.
</Tip>

<div id="generated-pages">
  ## Pages générées
</div>

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.

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

<div id="customize-a-page-for-a-single-symbol">
  ## Personnaliser une page pour un seul symbole
</div>

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 :

```mdx
---
title: "Client"
sdk: "class Client"
---

Créez un `Client` pour appeler l’API.
```

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

Si vous omettez `title` ou `description`, Mintlify utilise le titre et la description générés pour le symbole.

<ParamField path="kind" type="string" required>
  Le type de symbole : `class`, `interface`, `enum`, `function`, `type`, `variable`, `method` ou `property`.
</ParamField>

<ParamField path="name" type="string" required>
  Le nom du symbole tel qu’il apparaît dans l’artefact.
</ParamField>

<ParamField path="parent" type="string">
  Requis pour les cibles `method` et `property`. La classe, l’interface ou le type englobant.
</ParamField>

<ParamField path="format" type="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.
</ParamField>

<ParamField path="source" type="string">
  Remplace le `source` hérité. Requis lorsque la page ne se trouve pas sous un onglet ou un groupe avec `sdk`.
</ParamField>

<div id="use-remote-sources">
  ## Utiliser des sources distantes
</div>

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`) 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 :

```json
{
  "tab": "Java SDK",
  "sdk": {
    "format": "javadoc",
    "source": "https://repo1.maven.org/maven2/com/example/my-library/1.0.0/my-library-1.0.0-javadoc.jar",
    "directory": "sdk/java"
  }
}
```

Les artefacts distants ont une limite de téléchargement de 50 Mo et une limite de taille extraite de 200 Mo.

<div id="keep-references-up-to-date">
  ## Maintenir les références à jour
</div>

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

<div id="repository-setup">
  ## Configuration du dépôt
</div>

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.

<div id="sdk-and-documentation-in-the-same-repository">
  ### SDK et documentation dans le même dépôt
</div>

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.

```txt
docs-repo/
  docs.json
  content/
  sdk-artifacts/
    typedoc.json
```

<div id="sdk-in-a-separate-repository">
  ### SDK dans un dépôt séparé
</div>

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](/fr/api/update/trigger) depuis le pipeline de publication de votre SDK après avoir publié l’artefact.

<Tip>
  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.
</Tip>