OpenAPI

La rédaction manuelle de 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écrivent la structure et le fonctionnement de votre API.

La spécification OpenAPI (OAS) est un cadre que les développeurs utilisent pour documenter les API REST. Écrite en JSON ou YAML, elle décrit tous vos endpoints, 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 vos méthodes d'API — que la spécification soit fournie sous forme de fichier ou chargée depuis une URL.

GitBook prend en charge Swagger 2.0 ou OpenAPI 3.0 conformes.

POST /api/v3/pet HTTP/1.1
Host: 
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"
}

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

Testez-le (alimenté par Scalar)

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

Alimenté 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