Mintlify transforme les spécifications OpenAPI 3.0 et 3.1 (au format JSON ou YAML) en documentations d'API interactives et modernes. Au lieu de concevoir et d'entretenir manuellement des tableaux de paramètres de requête, d'en-têtes et de schémas de réponse, les équipes de développement et de rédaction technique peuvent importer directement leur fichier OpenAPI. Mintlify se charge d'analyser les points de terminaison, de générer des exemples de code dans plusieurs langages de programmation et de fournir une console d'évaluation dynamique (Playground) permettant d'exécuter des requêtes réelles depuis le navigateur.
La plateforme repose sur l'approche de la documentation en tant que code (Docs-as-code). Le fichier OpenAPI réside aux côtés des contenus Markdown dans un dépôt Git, l'ensemble étant administré par un fichier de configuration central (docs.json, ou mint.json pour les versions antérieures). Les équipes peuvent opter pour deux modes d'intégration : une génération entièrement automatisée sans maintenance de pages, ou la liaison précise de routes OpenAPI à des pages MDX dédiées pour combiner données techniques, guides didactiques et règles métier.
Prérequis et spécifications prises en charge
Avant de configurer Mintlify, assurez-vous que votre fichier répond aux exigences techniques de la plateforme :
- Versions prises en charge : Mintlify prend en charge nativement les spécifications OpenAPI (OAS) 3.0 et 3.1. Si votre schéma utilise encore Swagger 2.0, effectuez au préalable une migration vers OpenAPI 3.0.
- Formats de fichier : Les formats standard JSON (
.json) et YAML (.yamlou.yml) sont pris en charge. - Restrictions sur les références ($ref) : Mintlify résout parfaitement les références internes au sein d'un même document (par exemple
$ref: '#/components/schemas/User'). En revanche, les références externes réparties sur plusieurs fichiers ne sont pas prises en charge. Si votre schéma est morcelé en fichiers distincts, consolidez-le en un fichier unique (à l'aide d'outils comme Redocly CLI ou@apidevtools/swagger-cli) avant de l'intégrer dans Mintlify.
Étape 1 : Emplacement du fichier de spécification OpenAPI
Vous pouvez intégrer votre spécification OpenAPI par stockage local dans le dépôt ou via une URL distante :
-
Dépôt local (Recommandé) : Placez le fichier directement dans le dépôt de documentation. Il est d'usage de le placer à la racine du projet (par exemple
openapi.jsonouopenapi.yaml) ou dans un répertoire dédié aux interfaces (tel queapi-reference/openapi.jsonouspecs/v1.yaml). -
URL distante hébergée : Si votre chaîne d'intégration continue (CI/CD) publie automatiquement la spécification mise à jour sur un stockage cloud ou un CDN, vous pouvez renseigner directement une URL HTTPS (par exemple
https://api.example.com/specs/openapi.json). Pour les environnements de production, l'accès sécurisé en HTTPS est obligatoire.
Étape 2 : Configuration de la navigation dans docs.json
Pour intégrer la référence d'API dans la barre latérale du site, associez la spécification dans l'objet navigation du fichier docs.json.
Approche A : Génération automatique de la référence
Si vous souhaitez que Mintlify parcoure l'ensemble des routes, les classe automatiquement selon les balises (tags) d'OpenAPI et génère l'arborescence complète sans fichier manuel, déclarez le fichier dans un onglet ou un groupe de navigation :
{
"$schema": "https://mintlify.com/docs.json",
"name": "Acme API Docs",
"navigation": {
"tabs": [
{
"tab": "Guides",
"groups": [
{
"group": "Premiers pas",
"pages": ["introduction", "quickstart"]
}
]
},
{
"tab": "API Reference",
"openapi": "openapi.json"
}
]
}
}
Dans cette configuration, Mintlify analyse l'ensemble des méthodes définies sous paths, extrait descriptions, paramètres et schémas de réponse, et produit un catalogue interactif sans nécessiter la moindre page MDX.
Gestion de spécifications multiples
Lorsque l'infrastructure comporte plusieurs microservices ou versions d'API distinctes, indiquez un tableau de chemins d'accès :
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": [
"specs/v1/auth.json",
"specs/v1/billing.json",
"specs/v2/core.json"
]
}
]
}
}
Étape 3 : Contrôle granulaire via des pages MDX
Bien que l'automatisation intégrale soit pratique, les rédacteurs techniques doivent fréquemment enrichir les opérations d'explications contextuelles, d'avertissements sur les limites de fréquence ou de diagrammes d'architecture. Mintlify permet de lier des pages MDX à des endpoints précis grâce au Frontmatter.
1. Associer une page MDX à un endpoint spécifique
Créez un fichier MDX (par exemple api-reference/users/create.mdx) et déclarez la méthode HTTP ainsi que la route dans le champ openapi :
---
title: "Créer un utilisateur"
sidebarTitle: "Créer un utilisateur"
description: "Enregistre un nouveau compte utilisateur au sein de l'organisation"
openapi: "POST /v1/users"
---
## Vue d'ensemble
Avant d'appeler ce point de terminaison, vérifiez que votre application a obtenu la portée OAuth `users:write`.
<Warning>
L'adresse e-mail doit être unique pour l'ensemble de l'organisation. L'utilisation d'une adresse déjà enregistrée renverra une erreur `409 Conflict`.
</Warning>
## Notifications par Webhook
Une fois l'enregistrement validé, la plateforme émet automatiquement un événement `user.created` vers vos points de terminaison Webhook configurés.
Mintlify localise la définition POST /v1/users dans votre spécification globale, intègre le constructeur de requêtes interactif et les paramètres sur la page, et les imbrique naturellement dans vos explications rédigées en MDX.
Si votre documentation utilise plusieurs fichiers OpenAPI, indiquez le chemin du fichier pour éviter toute ambiguïté :
---
title: "Créer un utilisateur"
openapi: "specs/v1/auth.json POST /v1/users"
---
2. Génération en lot avec l'outil de scraping officiel
Pour générer rapidement des modèles de pages MDX pour un ensemble volumineux d'endpoints existants, exécutez la commande officielle d'extraction :
npx @mintlify/scraping@latest openapi-file ./openapi.json -o api-reference
Cet utilitaire convertit la spécification en fichiers MDX individuels dans le dossier api-reference, tous préconfigurés avec les balises Frontmatter nécessaires.
Étape 4 : Configuration du bac à sable interactif (Playground)
Le bac à sable interactif de Mintlify permet aux développeurs de tester les requêtes en temps réel. Pour assurer un fonctionnement sans accroc, configurez les éléments clés suivants :
1. Définir l'adresse de base du serveur (Base URL)
Mintlify extrait les adresses cibles du tableau servers présent dans votre document OpenAPI :
servers:
- url: https://api.example.com/v1
description: Serveur de production
- url: https://staging.api.example.com/v1
description: Environnement de test (Sandbox)
Si plusieurs serveurs sont configurés, le Playground proposera une liste déroulante permettant aux utilisateurs de basculer facilement d'un environnement à l'autre.
2. Déclaration de l'authentification et clés d'essai
Déclarez les mécanismes d'authentification sous components.securitySchemes. Mintlify affichera alors les champs de saisie correspondants (Bearer Token, API Key, Basic Auth, etc.) :
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Saisissez votre jeton d'accès API
security:
- bearerAuth: []
Pour simplifier les tests dans un environnement de démonstration, fournissez des clés de test prédéfinies à l'aide de l'extension x-default :
{
"components": {
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"x-default": "demo_pk_live_testing123"
}
}
}
}
3. Gestion du partage de ressources entre origines multiples (CORS)
Les requêtes du Playground étant émises directement par le navigateur de l'utilisateur, l'infrastructure API doit obligatoirement autoriser les requêtes cross-origin :
Access-Control-Allow-Origin: *(ou le domaine de votre documentation)Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONSAccess-Control-Allow-Headers: Authorization, Content-Type, X-API-Key
Si le serveur rejette les requêtes préalables de vérification (OPTIONS), les appels du Playground échoueront, même s'ils fonctionnent parfaitement via curl en ligne de commande.
Étape 5 : Personnalisation avec OpenAPI Overlays
Les spécifications générées automatiquement par le code source backend contiennent souvent des routes internes ou des descriptions trop sommaires. Pour éviter de modifier le code ou de gérer un fork divergent, Mintlify prend en charge la norme OpenAPI Overlay Specification (v1.1.0).
Un fichier de superposition définit des modifications ciblées en syntaxe JSONPath (update, remove, copy) :
overlay: 1.1.0
info:
title: Ajustements pour la documentation publique
version: 1.0.0
extends: ./openapi.json
actions:
- target: $.info.description
update: "Bienvenue sur la documentation officielle Acme. Découvrez nos interfaces et testez vos requêtes en direct."
- target: $.paths['/internal/system-health']
remove: true
- target: $.paths['/v1/billing'].post.summary
update: "Créer un abonnement récurrent"
Associez ensuite cette superposition dans votre fichier docs.json :
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": {
"source": "openapi.json",
"overlays": ["overlays/public-filter.yaml"]
}
}
]
}
}
Mintlify applique ces règles lors de la compilation : les routes privées sont masquées et les descriptions sont clarifiées, tout en conservant la spécification d'origine intacte côté ingénierie.
Étape 6 : Prévisualisation locale et validation CI/CD
Avant de déployer votre documentation en production, validez l'intégrité de vos fichiers à l'aide de la CLI Mintlify :
-
Lancer le serveur de développement local :
npm i -g mintlify mint dev -
Tester les schémas hébergés localement : Si la spécification est servie par un processus local (par exemple
http://localhost:8000/openapi.json), autorisez l'accès local :mint dev --local-schema -
Exécuter une validation stricte : Vérifiez l'absence de références brisées ou de schémas incomplets :
mint validate -
Intégration dans vos chaînes CI/CD : Ajoutez la commande
mint validatedans GitHub Actions ou GitLab CI. Dès qu'un développeur modifie la spécification, le pipeline vérifie la validité des définitions, protégeant ainsi la documentation de toute régression.