Si vous utilisez actuellement des pages MDX séparées pour vos endpoints d’API, vous pouvez migrer vers la génération automatique de pages à partir de votre spécification OpenAPI tout en conservant la personnalisation de chaque page. Cela peut vous aider à réduire le nombre de fichiers à maintenir et à améliorer la cohérence de votre documentation d’API. Vous pouvez définir les métadonnées et le contenu de chaque endpoint dans votre spécification OpenAPI et organiser les endpoints où vous le souhaitez dans la navigation.

​
Migration via CLI

La commande mint migrate-mdx est la méthode recommandée pour migrer des pages d’endpoint MDX vers des pages générées automatiquement. Cette commande :
  • Analyse la structure de navigation de votre docs.json.
  • Identifie les pages MDX qui génèrent des pages d’endpoint OpenAPI.
  • Extrait le contenu des fichiers MDX et le déplace vers l’extension x-mint dans votre spécification OpenAPI.
  • Met à jour votre docs.json pour référencer directement les endpoints OpenAPI au lieu des fichiers MDX.
  • Supprime les fichiers MDX d’endpoint d’origine.
Si vous avez déjà x-mint défini pour un endpoint et que vous avez également une page MDX avec du contenu pour cet endpoint, le contenu MDX écrasera les paramètres x-mint existants.Si vous avez plusieurs pages MDX pour le même endpoint avec des contenus différents, le script utilisera le contenu de la page qui apparaît en dernier dans votre docs.json.L’outil de migration ne permet pas de prévisualiser les modifications avant leur application.
1

Préparez votre spécification OpenAPI.

Assurez-vous que votre spécification OpenAPI est valide et inclut tous les endpoints que vous souhaitez documenter.Toute page MDX que vous souhaitez migrer doit comporter le frontmatter openapi: faisant référence à un endpoint.
Validez votre fichier OpenAPI à l’aide du Swagger Editor ou du Mint CLI.
2

Installez le Mint CLI

Si nécessaire, installez ou mettez à jour le Mint CLI.
3

Exécutez la commande de migration.

mint migrate-mdx

​
Étapes de migration manuelle

1

Préparez votre spécification OpenAPI.

Assurez-vous que votre spécification OpenAPI est valide et inclut tous les endpoints que vous souhaitez documenter.Pour les endpoints dont vous souhaitez personnaliser les métadonnées ou le contenu, ajoutez l’extension x-mint à l’endpoint. Consultez l’extension x-mint pour plus de détails.Pour les endpoints que vous souhaitez exclure de votre documentation, ajoutez l’extension x-hidden à l’endpoint.
Validez votre fichier OpenAPI à l’aide de Swagger Editor ou de la Mint CLI.
2

Mettez à jour votre structure de navigation.

Remplacez les références de pages MDX par des endpoints OpenAPI dans votre docs.json.
"navigation": {
  "groups": [
    {
      "group": "API Reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "overview",
        "authentication",
        "introduction",
        "GET /health",
        "quickstart", 
        "POST /users",
        "GET /users/{id}",
        "advanced-features"
      ]
    }
  ]
}
3

Supprimez les anciens fichiers MDX.

Après avoir vérifié que votre nouvelle navigation fonctionne correctement, supprimez les fichiers d’endpoint MDX dont vous n’avez plus besoin.
Vous pouvez personnaliser la façon dont votre documentation d’API apparaît dans votre navigation.
Combinez des pages d’API générées automatiquement avec d’autres pages : 
"navigation": {
  "groups": [
    {
      "group": "API Reference",
      "openapi": "openapi.json",
      "pages": [
        "api/overview",
        "GET /users",
        "POST /users", 
        "api/authentication"
      ]
    }
  ]
}

​
Plusieurs versions d’API

Organisez différentes versions d’API à l’aide d’onglets ou de groupes : 
"navigation": {
  "tabs": [
    {
      "tab": "API v1",
      "openapi": "specs/v1.json"
    },
    {
      "tab": "API v2", 
      "openapi": "specs/v2.json"
    }
  ]
}

​
Quand utiliser des pages MDX distinctes

Envisagez de conserver des pages MDX distinctes lorsque vous avez besoin de :
  • Contenu personnalisé détaillé par point de terminaison, comme des composants React ou des exemples volumineux.
  • Dispositions de page uniques.
  • Approches de documentation expérimentales pour des points de terminaison spécifiques.
Pour la plupart des cas d’usage, la navigation OpenAPI offre une meilleure maintenabilité et une cohérence accrues.