mintlify__docs/fr/guides/migrating-from-mdx.mdx

---
title: "Migrer les pages d’API MDX vers la navigation OpenAPI"
sidebarTitle: "Migrer de MDX vers OAS"
description: "Migrer vers la génération OpenAPI automatisée avec une navigation flexible."
keywords: ["Migration d’API", "mint migrate-mdx", "Migration OpenAPI", "extension x-mint"]
---

Si vous utilisez actuellement des pages MDX individuelles 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 possibilité de personnaliser chaque page individuellement. 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 champs metadata et content pour chaque endpoint dans votre spécification OpenAPI, et organiser les endpoints où vous le souhaitez dans votre navigation.

<div id="cli-migration">
  ## Migration via la CLI
</div>

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` dans votre `docs.json`.
* Identifie les pages MDX qui génèrent des pages d’endpoint OpenAPI.
* Extrait le contenu des fichiers MDX et le transfère 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.

<Info>
  Si vous avez déjà défini `x-mint` pour un endpoint et que vous avez également une page MDX contenant du contenu pour ce même endpoint, le contenu MDX remplacera 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 de les appliquer.
</Info>

<Steps>
  <Step title="Préparez votre spécification OpenAPI.">
    Assurez-vous que votre spécification OpenAPI est valide et inclut tous les endpoints que vous souhaitez documenter.

    Toutes les pages MDX que vous souhaitez migrer doivent comporter un frontmatter `openapi:` pointant vers un endpoint.

    <Tip>
      Validez votre fichier OpenAPI à l’aide de [Swagger Editor](https://editor.swagger.io/) ou de la [Mint CLI](https://www.npmjs.com/package/mint).
    </Tip>
  </Step>

  <Step title="Installez la Mint CLI">
    Si nécessaire, installez ou mettez à jour la [Mint CLI](/fr/installation).
  </Step>

  <Step title="Exécutez la commande de migration.">
    ```bash
    mint migrate-mdx
    ```
  </Step>
</Steps>

<div id="manual-migration-steps">
  ## Étapes de migration manuelle
</div>

<Steps>
  <Step title="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 chaque endpoint pour lequel vous souhaitez personnaliser les métadonnées ou le contenu, ajoutez l’extension `x-mint` à l’endpoint. Consultez l’[extension x-mint](/fr/api-playground/openapi-setup#customize-your-endpoint-pages) pour plus de détails.

    Pour chaque endpoint que vous souhaitez exclure de votre documentation, ajoutez l’extension `x-hidden` à l’endpoint.

    <Info>
      Validez votre fichier OpenAPI à l’aide de [Swagger Editor](https://editor.swagger.io/) ou de l’[interface en ligne de commande (CLI) Mint](https://www.npmjs.com/package/mint).
    </Info>
  </Step>
  
  <Step title="Mettez à jour la structure de votre navigation.">
    Remplacez les références de pages MDX par des endpoints OpenAPI dans votre `docs.json`.

    ```json
    "navigation": {
      "groups": [
        {
          "group": "Référence d’API",
          "openapi": "/path/to/openapi.json",
          "pages": [
            "overview",
            "authentication",
            "introduction",
            "GET /health",
            "quickstart", 
            "POST /users",
            "GET /users/{id}",
            "advanced-features"
          ]
        }
      ]
    }
    ```

  </Step>

  <Step title="Supprimez les anciens fichiers MDX.">
    Après avoir vérifié que votre nouvelle navigation fonctionne correctement, supprimez les fichiers MDX correspondant aux endpoints dont vous n’avez plus besoin.
  </Step>
</Steps>

<div id="navigation-patterns">
  ## Modèles de navigation
</div>

Vous pouvez personnaliser la manière dont la documentation de votre API apparaît dans votre navigation.

<div id="mixed-content-navigation">
  ### Navigation à contenu mixte
</div>

Combinez des pages d’API générées automatiquement avec d’autres pages :

```json
"navigation": {
  "groups": [
    {
      "group": "Référence API",
      "openapi": "openapi.json",
      "pages": [
        "api/overview",
        "GET /users",
        "POST /users", 
        "api/authentication"
      ]
    }
  ]
}
```

<div id="multiple-api-versions">
  ### Plusieurs versions d’API
</div>

Organisez différentes versions d’API à l’aide d’Onglets ou de groups :

```json
"navigation": {
  "tabs": [
    {
      "tab": "API v1",
      "openapi": "specs/v1.json"
    },
    {
      "tab": "API v2", 
      "openapi": "specs/v2.json"
    }
  ]
}
```

<div id="when-to-use-individual-mdx-pages">
  ## Quand utiliser des pages MDX individuelles
</div>

Envisagez de conserver des pages MDX individuelles lorsque vous avez besoin de :

* Contenu très personnalisé et volumineux par endpoint, comme des composants React ou des exemples détaillés.
* Mises en page uniques.
* Approches de documentation expérimentales pour des endpoints spécifiques.

Pour la plupart des cas d’utilisation, la navigation OpenAPI offre une meilleure maintenabilité et une plus grande cohérence.