Skip to main content
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 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 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 ou GitLab.
  • Gestion des versions : maintenez la documentation pour plusieurs versions afin que les développeurs sur d’anciennes versions puissent toujours trouver des informations précises.

​
Prérequis

Si vous n’avez pas encore créé de projet Mintlify, consultez le Démarrage rapide 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

​
Migrer la documentation existante

Si vous créez une nouvelle documentation à partir de zéro, passez à la section Planifier la structure de votre documentation.

​
Auditer le contenu existant

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 ?

​
Exportez votre contenu existant

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

​
Planifiez la structure de votre documentation

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

​
Configurez la référence de votre API

Si vous avez une API, générez une référence interactive à partir de votre spécification OpenAPI.
1

Ajoutez votre spécification OpenAPI

Ajoutez votre fichier de spécification OpenAPI à votre projet. Vous pouvez utiliser le format YAML ou JSON.
your-project/
├── docs.json
├── openapi.yaml
└── api-reference/
    └── overview.mdx
2

Configurez la spécification dans docs.json

Référencez votre fichier OpenAPI dans votre configuration docs.json.
Exemple de configuration
{
  "openapi": "openapi.yaml"
}
3

Ajoutez les points de terminaison à la navigation

Ajoutez les points de terminaison à la navigation de votre docs.json. Consultez la page Configuration OpenAPI pour les options de configuration.
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"
  ]
}

​
Configurer l’Assistant

L’Assistant aide les développeurs à trouver des réponses et à comprendre les exemples de code. Configurez-le depuis votre dashboard.
  • 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.

​
Configurer la gestion des versions

Si vous maintenez plusieurs versions d’API, configurez la gestion des versions afin que les développeurs puissent trouver la documentation de leur version.
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.

​
Connectez votre référentiel

Installez la GitHub App Mintlify pour garder la documentation synchronisée avec votre base de code et faciliter les contributions.
1

Connectez votre référentiel

Associez votre référentiel GitHub dans le Dashboard. Cela active les déploiements automatiques lorsque vous poussez des modifications.
2

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.
Si vous utilisez GitLab, consultez GitLab pour les instructions de configuration.

​
Maintenez votre documentation

La documentation développeur nécessite des mises à jour régulières afin que les informations restent exactes et utilisables.
1

Maintenir la référence d'API à jour

Mettez à jour votre spécification OpenAPI à chaque nouvelle version. Si votre spécification est générée à partir du code, automatisez cela dans votre processus de mise en production.
2

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

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 pour plus d’informations.
4

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 pour plus d’informations.

​
Prochaines étapes

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.