# OpenAPI

Rédiger manuellement la documentation d’une API REST peut prendre du temps. Heureusement, GitBook simplifie cette tâche en vous permettant d’importer des documents OpenAPI, qui détaillent la structure et les fonctionnalités de votre API.

La spécification OpenAPI (OAS) est un cadre que les développeurs utilisent pour documenter les API REST. Rédigée en JSON ou en YAML, elle décrit tous vos points de terminaison, paramètres, schémas et méthodes d’authentification.

Une fois importés dans GitBook, ces documents sont transformés en blocs d’API interactifs et testables qui représentent visuellement les méthodes de votre API — que la spécification soit fournie sous forme de fichier ou chargée depuis une URL.

GitBook prend en charge [Swagger 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) ou [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md) fichiers conformes.

{% openapi src="<https://petstore3.swagger.io/api/v3/openapi.json>" path="/pet" method="post" %}
<https://petstore3.swagger.io/api/v3/openapi.json>
{% endopenapi %}

### Testez-le (propulsé par Scalar)

Le bloc OpenAPI de GitBook prend également en charge une fonctionnalité « testez-le », qui permet à vos utilisateurs de tester les méthodes de votre API avec des données et des paramètres remplis depuis l’éditeur.

Propulsé par [Scalar](https://scalar.com/), vous n’aurez pas besoin de quitter la documentation pour voir vos méthodes d’API en action. Voir un exemple ci-dessus.

#### FAQ

<details>

<summary>Pourquoi ma spécification ne se charge-t-elle pas ?</summary>

{% hint style="info" %}
**Remarque :** Ces informations s’appliquent uniquement aux **spécifications ajoutées par URL**.
{% endhint %}

Si vous avez ajouté votre spécification via une URL, votre API doit [autoriser les requêtes cross-origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Origin) GET depuis votre site de documentation. Dans les paramètres CORS de votre API, autorisez l’origine exacte où votre documentation est hébergée (par exemple, `https://your-site.gitbook.io` ou `https://docs.example.com`).\
\
Si votre point de terminaison est सार्वजनिक et n’utilise pas d’identifiants, vous pouvez également renvoyer : `Access-Control-Allow-Origin: *`\ <br>

</details>