OpenAPI

Ajoutez une spécification OpenAPI à une page et laissez vos utilisateurs tester les endpoints directement sur la page avec des blocs interactifs.

Rédiger manuellement la documentation d’une API REST peut être un processus chronophage. 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écanismes 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.

Compatibilité OpenAPI

GitBook prend en charge l’importation et le rendu des versions de spécification suivantes :

• Swagger 2.0 — pris en charge.
• OpenAPI 3.0 — pris en charge.
• OpenAPI 3.1 — pris en charge, y compris les fonctionnalités propres à OpenAPI 3.1 telles que les webhooks.

Add a new pet to the store.

post

Add a new pet to the store.

Scopes requis

Cet endpoint nécessite les scopes suivants :

• : modify pets in your account
• : read your pets

Autorisations

petstore_auth

OAuth2implicitRequis

Authorization URL:

Corps

application/jsonapplication/xmlapplication/x-www-form-urlencoded

idinteger · int64OptionnelExample: 10

namestringRequisExample: doggie

photoUrlsstring[]Requis

statusstring · enumOptionnel

pet status in the store

Valeurs possibles:

Réponses

200

Successful operation

application/jsonapplication/xml

idinteger · int64OptionnelExample: 10

namestringRequisExample: doggie

photoUrlsstring[]Requis

statusstring · enumOptionnel

pet status in the store

Valeurs possibles:

400

Invalid input

422

Validation exception

default

Unexpected error

post/pet

HTTPcURLJavaScriptPython

POST /api/v3/pet HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 133

{
  "id": 10,
  "name": "doggie",
  "category": {
    "id": 1,
    "name": "Dogs"
  },
  "photoUrls": [
    "text"
  ],
  "tags": [
    {
      "id": 1,
      "name": "text"
    }
  ],
  "status": "available"
}

application/jsonapplication/xmlapplication/x-www-form-urlencoded

{
  "id": 10,
  "name": "doggie",
  "category": {
    "id": 1,
    "name": "Dogs"
  },
  "photoUrls": [
    "text"
  ],
  "tags": [
    {
      "id": 1,
      "name": "text"
    }
  ],
  "status": "available"
}

Tester (propulsé par Scalar)

Le bloc OpenAPI de GitBook prend également en charge la fonctionnalité « tester », qui permet à vos utilisateurs de tester vos méthodes d’API avec des données et des paramètres renseignés depuis l’éditeur.

Propulsé par Scalar, vous n’aurez pas besoin de quitter la documentation pour voir vos méthodes d’API en action. Voir un exemple ci-dessus.

FAQ

Pourquoi ma spécification ne se charge-t-elle pas ?

Remarque : Ces informations ne s’appliquent qu’aux spécifications ajoutées par URL.

Si vous avez ajouté votre spécification via URL, votre API doit autoriser les requêtes inter-origines 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 ex. : https://your-site.gitbook.io ou https://docs.example.com). Si votre point de terminaison est public et n’utilise pas d’identifiants, vous pouvez également renvoyer : Access-Control-Allow-Origin: *