Créer manuellement des pages d'API

Vous pouvez définir manuellement des endpoints d’API dans des pages MDX individuelles. Cette approche est particulièrement utile pour de petites API ou pour le prototypage.

Configuration

Configurez les paramètres de votre API

Dans votre fichier docs.json, définissez votre URL de base et votre méthode d’authentification.

Example docs.json

"api": {
  "mdx": {
    "server": "https://api.acme.com/",
    "auth": {
      "method": "key",
      "name": "x-api-key"
    }
  }
}

Si vous souhaitez masquer le bac à sable d’API, définissez le champ display sur none. Vous n’avez pas besoin d’inclure de méthode d’authentification si vous masquez le bac à sable d’API.

"api": {
  "playground": {
    "display": "none"
  }
}

Consultez la liste complète des configurations d’API dans Settings.

Créez les pages de vos endpoints

Créez un fichier MDX pour chaque endpoint. Définissez les champs title et api dans le frontmatter :

---
title: 'Créer un nouvel utilisateur'
api: 'POST /v1/users'
---

Le champ de frontmatter api accepte soit une URL complète, soit un chemin relatif :

URL complète comme POST https://api.acme.com/v1/users. Le champ server dans docs.json est ignoré pour cet endpoint.
Chemin relatif comme POST /v1/users. Nécessite un champ server dans docs.json. L’URL du serveur est préfixée au chemin.

Spécifiez les paramètres de chemin en les entourant de {} :

https://api.example.com/v1/endpoint/{userId}

Pour surcharger le mode d’affichage global du playground pour une page spécifique, ajoutez playground au frontmatter :

---
title: 'Créer un nouvel utilisateur'
api: 'POST https://api.mintlify.com/user'
playground: 'none'
---

Options :

playground: 'interactive' - Afficher le playground interactif (par défaut)
playground: 'simple' - Afficher un endpoint copiable sans playground
playground: 'none' - Masquer le playground entièrement

Ajouter des paramètres et des réponses

Utilisez les champs de paramètres et de réponse pour documenter les paramètres et les valeurs renvoyées par votre endpoint.

<ParamField path="userId" type="string" required>
  Identifiant unique de l'utilisateur
</ParamField>

<ParamField body="email" type="string" required>
  Adresse e-mail de l'utilisateur
</ParamField>

<ResponseField name="id" type="string" required>
  Identifiant unique de l'utilisateur nouvellement créé
</ResponseField>

<ResponseField name="email" type="string" required>
  Adresse e-mail de l'utilisateur
</ResponseField>

Ajoutez vos points de terminaison d’API à votre documentation

Ajoutez vos pages d’endpoint à la navigation en mettant à jour le champ pages de votre fichier docs.json :

docs.json

"navigation": {
  "tabs": [
    {
      "tab": "Référence de l'API",
      "groups": [
        {
          "group": "Users",
          "pages": [
            "api-reference/users/create-user",
            "api-reference/users/get-user",
            "api-reference/users/update-user"
          ]
        },
        {
          "group": "Orders",
          "pages": [
            "api-reference/orders/create-order",
            "api-reference/orders/list-orders"
          ]
        }
      ]
    }
  ]
}

Chaque chemin de page correspond à un fichier MDX dans votre référentiel de documentation. Par exemple, api-reference/users/create-user.mdx. Pour en savoir plus sur la structuration de votre documentation, consultez Navigation.Si vous disposez d’une spécification OpenAPI, vous pouvez faire référence à des endpoints directement dans votre navigation sans créer de fichiers MDX individuels. Faites référence à des endpoints spécifiques en incluant le chemin du fichier OpenAPI et l’endpoint :

docs.json

"navigation": {
  "pages": [
    "introduction",
    "/path/to/users-openapi.json POST /users",
    "/path/to/orders-openapi.json GET /orders"
  ]
}

Vous pouvez également définir une spécification OpenAPI par défaut pour un groupe de navigation et y référencer les endpoints par méthode et par chemin :

docs.json

{
  "group": "Référence de l'API",
  "openapi": "/path/to/openapi-v1.json",
  "pages": [
    "overview",
    "authentication",
    "GET /users",
    "POST /users",
    {
      "group": "Orders",
      "openapi": "/path/to/openapi-v2.json",
      "pages": [
        "GET /orders",
        "POST /orders"
      ]
    }
  ]
}

Pour plus de détails sur l’intégration OpenAPI, consultez la page Configuration OpenAPI.

Activer l’authentification

Vous pouvez configurer l’authentification globalement dans docs.json, ou la surcharger sur des pages spécifiques à l’aide du champ authMethod dans le frontmatter. Une méthode définie au niveau d’une page prend le pas sur le paramètre global.

Jeton d’authentification Bearer

"api": {
  "mdx": {
    "auth": {
      "method": "bearer"
    }
  }
}

---
title: "Titre de votre page"
authMethod: "bearer"
---

Authentification basique

"api": {
  "mdx": {
    "auth": {
      "method": "basic"
    }
  }
}

---
title: "Titre de votre page"
authMethod: "basic"
---

Clé API

"api": {
  "mdx": {
    "auth": {
      "method": "key",
      "name": "x-api-key"
    }
  }
}

---
title: "Titre de la page"
authMethod: "key"
---

Aucun

Pour désactiver l’authentification sur une page spécifique, définissez authMethod sur none :

Page Metadata

---
title: "Titre de votre page"
authMethod: "none"
---

​Configuration

​Utiliser des endpoints OpenAPI dans la navigation

​Activer l’authentification

​Jeton d’authentification Bearer

​Authentification basique

​Clé API

​Aucun

Configuration

Utiliser des endpoints OpenAPI dans la navigation

Activer l’authentification

Jeton d’authentification Bearer

Authentification basique

Clé API

Aucun