mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
fed930aa2d
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
241 lines
9.9 KiB
Plaintext
241 lines
9.9 KiB
Plaintext
---
|
||
title: "Créer une documentation développeur"
|
||
sidebarTitle: "Documentation développeur"
|
||
description: "Créez une documentation développeur qui aide les ingénieurs à intégrer vos API, SDK et outils, avec quickstarts, références et guides détaillés."
|
||
keywords: ["documentation développeur", "documentation d'API", "documentation SDK", "documentation technique", "portail développeur"]
|
||
---
|
||
|
||
La documentation développeur aide les développeurs à comprendre votre produit et à s'y intégrer. Une bonne documentation permet aux développeurs de faire plus avec votre produit, réduit la charge du support, accélère l’adoption et améliore l’expérience développeur.
|
||
|
||
Mintlify fournit une infrastructure conçue pour la documentation développeur.
|
||
|
||
* **Génération de références d’API** : générez des [références d’API](/fr/api-playground/overview) interactives à partir de spécifications OpenAPI qui permettent aux développeurs de tester des endpoints directement dans votre documentation.
|
||
* **Blocs de code avec explications** : l’[Assistant](/fr/assistant/index) explique les exemples de code dans leur contexte, aidant les développeurs à comprendre les détails d’implémentation.
|
||
* **Synchronisation Git** : gardez la documentation synchronisée avec votre base de code en utilisant [GitHub](/fr/deploy/github) ou [GitLab](/fr/deploy/gitlab).
|
||
* **Gestion des versions** : maintenez la documentation pour plusieurs [versions](/fr/organize/navigation#versions) afin que les développeurs sur d’anciennes versions puissent toujours trouver des informations précises.
|
||
|
||
<div id="prerequisites">
|
||
## Prérequis
|
||
</div>
|
||
|
||
Si vous n'avez pas encore créé de projet Mintlify, consultez le [Démarrage rapide](/fr/quickstart) pour déployer votre site.
|
||
|
||
* Votre spécification d’API au format OpenAPI (si vous documentez une API)
|
||
* Un référentiel Git pour votre documentation
|
||
* Un accès administrateur à votre organisation Mintlify
|
||
|
||
<div id="migrate-existing-documentation">
|
||
## Migrer la documentation existante
|
||
</div>
|
||
|
||
Si vous créez une nouvelle documentation à partir de zéro, passez à la section [Planifier la structure de votre documentation](#plan-your-documentation-structure).
|
||
|
||
<div id="audit-existing-content">
|
||
### Auditer le contenu existant
|
||
</div>
|
||
|
||
Passez en revue votre documentation actuelle pour comprendre ce que vous avez déjà et ce que vous devez migrer.
|
||
|
||
* **Référence d'API** : Est-elle générée à partir d'une spécification ou rédigée manuellement ? Quels endpoints documentez-vous ?
|
||
* **Guides et tutoriels** : Quels guides d'intégration existent ? Sont-ils à jour ?
|
||
* **Exemples de code** : Quels langages et frameworks utilisez-vous ?
|
||
* **Documentation SDK** : Avez-vous une documentation distincte pour chaque SDK ?
|
||
* **Journal des modifications** : Tenez-vous un journal des modifications ou des notes de version ?
|
||
* **Metadata** : Disposez-vous de metadata pour votre contenu, comme des dates, des auteurs et des tags ?
|
||
|
||
<div id="export-your-existing-content">
|
||
### Exportez votre contenu existant
|
||
</div>
|
||
|
||
* Exportez en **Markdown** pour une migration simplifiée vers Mintlify.
|
||
* Exportez les **spécifications OpenAPI** pour la documentation de référence de votre API.
|
||
* Exportez en **HTML** si Markdown n’est pas disponible, puis convertissez-le en Markdown.
|
||
|
||
<div id="plan-your-documentation-structure">
|
||
## Planifiez la structure de votre documentation
|
||
</div>
|
||
|
||
La documentation pour développeurs inclut généralement plusieurs types de contenus. Structurez votre navigation en fonction de la façon dont vos utilisateurs comprennent votre produit.
|
||
|
||
```json docs.json example
|
||
{
|
||
"navigation": {
|
||
"groups": [
|
||
{
|
||
"group": "Get Started",
|
||
"pages": [
|
||
"introduction",
|
||
"quickstart",
|
||
"authentication"
|
||
]
|
||
},
|
||
{
|
||
"group": "Guides",
|
||
"pages": [
|
||
"guides/webhooks",
|
||
"guides/error-handling",
|
||
"guides/rate-limits",
|
||
"guides/pagination"
|
||
]
|
||
},
|
||
{
|
||
"group": "Référence API",
|
||
"pages": [
|
||
"api-reference/overview",
|
||
"api-reference/users",
|
||
"api-reference/orders",
|
||
"api-reference/products"
|
||
]
|
||
},
|
||
{
|
||
"group": "SDKs",
|
||
"pages": [
|
||
"sdks/javascript",
|
||
"sdks/python",
|
||
"sdks/go"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
Pour davantage d’options de configuration, voir [Navigation](/fr/organize/navigation).
|
||
|
||
<div id="set-up-your-api-reference">
|
||
## Configurez la référence de votre API
|
||
</div>
|
||
|
||
Si vous avez une API, générez une référence interactive à partir de votre spécification OpenAPI.
|
||
|
||
<Steps>
|
||
<Step title="Ajoutez votre spécification OpenAPI">
|
||
Ajoutez votre fichier de spécification OpenAPI à votre projet. Vous pouvez utiliser le format YAML ou JSON.
|
||
|
||
```text
|
||
your-project/
|
||
├── docs.json
|
||
├── openapi.yaml
|
||
└── api-reference/
|
||
└── overview.mdx
|
||
```
|
||
</Step>
|
||
|
||
<Step title="Configurez la spécification dans docs.json">
|
||
Référencez votre fichier OpenAPI dans votre configuration `docs.json`.
|
||
|
||
```json Exemple de configuration
|
||
{
|
||
"openapi": "openapi.yaml"
|
||
}
|
||
```
|
||
</Step>
|
||
|
||
<Step title="Ajoutez les points de terminaison à la navigation">
|
||
Ajoutez les points de terminaison à la navigation de votre `docs.json`. Consultez la page [Configuration OpenAPI](/fr/api-playground/openapi-setup) pour les options de configuration.
|
||
|
||
```json Exemple de navigation
|
||
{
|
||
"group": "Référence API",
|
||
"pages": [
|
||
"api-reference/overview",
|
||
"api-reference/users/list-users",
|
||
"api-reference/users/get-user",
|
||
"api-reference/users/create-user"
|
||
]
|
||
}
|
||
```
|
||
</Step>
|
||
</Steps>
|
||
|
||
<div id="set-up-the-assistant">
|
||
## Configurer l'Assistant
|
||
</div>
|
||
|
||
L'Assistant aide les développeurs à trouver des réponses et à comprendre les exemples de code. Configurez-le depuis votre [dashboard](https://dashboard.mintlify.com/products/assistant/settings).
|
||
|
||
* **Exemples de questions** : Ajoutez des questions à destination des développeurs comme « Comment authentifier des requêtes API ? » ou « Montre-moi comment gérer les webhooks. »
|
||
* **Explications de code** : L'Assistant peut expliquer des code blocks dans leur contexte lorsque les développeurs posent des questions sur des exemples spécifiques.
|
||
|
||
<div id="set-up-versioning">
|
||
## Configurer la gestion des versions
|
||
</div>
|
||
|
||
Si vous maintenez plusieurs versions d’API, configurez la gestion des versions afin que les développeurs puissent trouver la documentation de leur version.
|
||
|
||
```json Versioning example
|
||
{
|
||
"versions": ["v2", "v1"],
|
||
"navigation": {
|
||
"groups": [
|
||
{
|
||
"group": "Référence de l'API",
|
||
"version": "v2",
|
||
"pages": ["v2/api-reference/users"]
|
||
},
|
||
{
|
||
"group": "Référence de l'API",
|
||
"version": "v1",
|
||
"pages": ["v1/api-reference/users"]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
Pour en savoir plus, consultez [Versions](/fr/organize/navigation#versions).
|
||
|
||
<div id="connect-to-your-repository">
|
||
## Connectez votre référentiel
|
||
</div>
|
||
|
||
Installez la [GitHub App](/fr/deploy/github) Mintlify pour garder la documentation synchronisée avec votre base de code et faciliter les contributions.
|
||
|
||
<Steps>
|
||
<Step title="Connectez votre référentiel">
|
||
Associez votre référentiel GitHub dans le [Dashboard](https://dashboard.mintlify.com). Cela active les déploiements automatiques lorsque vous poussez des modifications.
|
||
</Step>
|
||
|
||
<Step title="Configurez les paramètres de branche">
|
||
Définissez votre branche de production et activez les déploiements de prévisualisation pour les pull requests (demandes de fusion). Cela vous permet d’examiner les modifications de la documentation avant leur mise en ligne.
|
||
</Step>
|
||
</Steps>
|
||
|
||
<Note>
|
||
Si vous utilisez GitLab, consultez [GitLab](/fr/deploy/gitlab) pour les instructions de configuration.
|
||
</Note>
|
||
|
||
<div id="maintain-your-documentation">
|
||
## Maintenez votre documentation
|
||
</div>
|
||
|
||
La documentation développeur nécessite des mises à jour régulières afin que les informations restent exactes et utilisables.
|
||
|
||
<Steps>
|
||
<Step title="Maintenir la référence d'API à jour">
|
||
Mettez à jour votre spécification OpenAPI à chaque nouvelle version. Si vous générez votre spécification à partir du code, automatisez cela dans votre processus de mise en production.
|
||
</Step>
|
||
|
||
<Step title="Mettre à jour les exemples de code">
|
||
Passez en revue les exemples de code lorsque vous publiez de nouvelles versions de SDK ou des mises à jour produit. Des exemples obsolètes entraînent des échecs d'intégration et des demandes au support technique.
|
||
</Step>
|
||
|
||
<Step title="Maintenir un journal des modifications">
|
||
Documentez les changements majeurs, les nouvelles fonctionnalités et les mises en obsolescence. Les développeurs s'appuient sur le journal des modifications pour comprendre ce qui a changé entre les versions. Voir [Journal des modifications](/fr/create/changelogs) pour plus d'informations.
|
||
</Step>
|
||
|
||
<Step title="Surveiller les retours">
|
||
Passez en revue les conversations de l'Assistant et les Analytics de recherche pour identifier les lacunes de votre documentation. Si les développeurs posent à plusieurs reprises des questions sur le même sujet, améliorez cette section. Voir [Maintenance](/fr/guides/maintenance) pour plus d'informations.
|
||
</Step>
|
||
</Steps>
|
||
|
||
<div id="next-steps">
|
||
## Prochaines étapes
|
||
</div>
|
||
|
||
Votre documentation pour développeurs est prête à être lancée. Après le déploiement :
|
||
|
||
1. Annoncez la mise en ligne de la documentation à votre communauté de développeurs.
|
||
2. Surveillez les tendances de recherche et les conversations de l'Assistant pour identifier les lacunes.
|
||
3. Mettez en place un processus pour mettre à jour la documentation à chaque nouvelle version de l'API.
|
||
4. Recueillez les retours des développeurs pour améliorer le contenu au fil du temps. |