> ## Documentation Index
> Fetch the complete documentation index at: https://omer-914cc1c6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration des pages MDX d’API vers la navigation OpenAPI

> Passez de pages MDX d’endpoint individuelles à une génération OpenAPI automatisée avec une navigation flexible

Si vous utilisez actuellement des pages `MDX` distinctes pour vos endpoints d’API, vous pouvez migrer vers l’autogénération de pages à partir de votre spécification OpenAPI tout en conservant la possibilité de personnaliser 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 des metadata et du contenu 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 `docs.json` pour la navigation.
* 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 originaux.

<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 cet 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 leur application.
</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.

    Toute page MDX que vous souhaitez migrer doit avoir le frontmatter `openapi:` faisant référence à un endpoint.

    <Tip>
      Validez votre fichier OpenAPI à l’aide du [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 theme={null}
    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 points de terminaison que vous souhaitez documenter.

    Pour les points de terminaison dont vous souhaitez personnaliser les metadata ou le content, ajoutez l’extension `x-mint` au point de terminaison. Voir [x-mint extension](/fr/api-playground/openapi-setup#x-mint-extension) pour plus de détails.

    Pour les points de terminaison que vous souhaitez exclure de votre documentation, ajoutez l’extension `x-hidden` au point de terminaison.

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

  <Step title="Mettez à jour votre structure de navigation.">
    Remplacez les références de pages `MDX` par des points de terminaison OpenAPI dans votre `docs.json`.

    ```json theme={null}
    "navigation": {
      "groups": [
        {
          "group": "API Reference",
          "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` de points de terminaison dont vous n’avez plus besoin.
  </Step>
</Steps>

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

Vous pouvez personnaliser l’apparence de la documentation de votre API dans la 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 theme={null}
"navigation": {
  "groups": [
    {
      "group": "Référence API",
      "openapi": "openapi.json",
      "pages": [
        "api/overview",
        "GET /users",
        "POST /users", 
        "api/authentification"
      ]
    }
  ]
}
```

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

Organisez différentes versions d’API à l’aide d’onglets ou de groupes :

```json theme={null}
"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 personnalisé approfondi par point de terminaison, comme des composants React ou des exemples détaillés.
* Des mises en page uniques.
* Des 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 meilleure cohérence.