Champs dans OpenAPI

OpenAPI (anciennement connu sous le nom de Swagger) est une spécification pour la construction d'API (Application Programming Interfaces). Il fournit un moyen standard de définir, de documenter et d'utiliser les API RESTful. La spécification OpenAPI est écrite au format YAML ou JSON et comprend un certain nombre de champs qui sont utilisés pour définir divers aspects de l'API.

Voici quelques-uns des champs les plus couramment utilisés dans OpenAPI :

openapi: spécifie la version de la spécification OpenAPI utilisée.
info: contient des informations sur l'API, telles que le titre, la description, la version et les coordonnées.
servers: spécifie le ou les serveurs sur lesquels l'API est hébergée.
paths: Définit les points de terminaison (URL) de l'API et les méthodes HTTP (GET, POST, PUT, DELETE, etc.) qui peuvent être utilisées pour y accéder.
components: contient des éléments réutilisables de l'API, tels que des schémas, des schémas de sécurité et des réponses.
security: spécifie les schémas de sécurité utilisés par l'API.
tags: fournit des métadonnées pour regrouper et organiser les opérations et les points de terminaison.
externalDocs: Contient des liens vers la documentation externe relative à l'API.

Ce ne sont que quelques exemples des champs qui peuvent être utilisés dans une spécification OpenAPI. La liste complète des champs se trouve dans la documentation officielle de la spécification OpenAPI.

Comment Apigit contribue-t-il à remplir ces champs ?

Bien que tous les champs d'une spécification OpenAPI ne soient pas strictement obligatoires, certains champs doivent être inclus pour garantir que la spécification est valide et complète. Voici quelques-uns des champs indispensables dans une spécification OpenAPI :

openapi: spécifie la version de la spécification OpenAPI utilisée. Ce champ est obligatoire et doit être inclus au niveau racine de la spécification.
info: contient des informations sur l'API, telles que le titre, la description, la version et les coordonnées. Ce champ est obligatoire et doit également être inclus au niveau racine de la spécification.
paths: Définit les points de terminaison (URL) de l'API et les méthodes HTTP (GET, POST, PUT, DELETE, etc.) qui peuvent être utilisées pour y accéder. Ce champ est également obligatoire et doit être inclus au niveau racine de la spécification.
servers: spécifie le ou les serveurs sur lesquels l'API est hébergée. Ce champ n'est pas strictement obligatoire, mais il est recommandé de l'inclure pour fournir des informations sur le ou les serveurs hébergeant l'API.
components: contient des éléments réutilisables de l'API, tels que des schémas, des schémas de sécurité et des réponses. Ce champ n'est pas strictement obligatoire, mais il est recommandé de l'inclure pour une meilleure organisation et réutilisation de la spécification.

Ce sont les champs essentiels qui doivent être inclus dans une spécification OpenAPI pour s'assurer qu'elle est valide et complète. D'autres domaines tels quesecurity,tags, etexternalDocs peuvent également être inclus en fonction des besoins de l'API et du niveau de détail requis dans la spécification.

Pour ajouter une spécification d'API à votre tableau de bord Apigit, cliquez sur le signe "+" situé dans le coin supérieur gauche. Saisissez un nom de chemin, tel que "test/test.json", ainsi que d'autres informations pertinentes telles que le "titre" et la "version". Un fichier vide aidera à remplir tous ces champs obligatoires.

Créer un fichier de spécifications vide

Ensuite, votre code json serait comme ci-dessous.

{
  "openapi": "3.0.3",
  "info": {
    "title": "titlet",
    "description": "just a test",
    "termsOfService": "",
    "contact": {
      "email": ""
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "1.0"
  },
  "externalDocs": {
    "description": "Find out more about spec",
    "url": ""
  },
  "servers": [],
  "tags": [
    {
      "name": "Default",
      "description": ""
    }
  ],
  "paths": {},
  "components": {
    "schemas": {},
    "securitySchemes": {}
  }
}

Comment Apigit aide-t-il davantage ?

Pour illustrer comment Apigit aide à remplir un champ au format Formulaire, voici quelques exemples. AjouterField parameter dansForm

Ensuite, votre code json serait comme ci-dessous.

"components": {
    "schemas": {},
    "securitySchemes": {},
    "parameters": {
      "petId": {
        "in": "path",
        "required": true,
        "description": "",
        "schema": {
          "type": "string"
        },
        "name": "PetId"
      }
    }
  }

AjouterField path dansForm

Ensuite, votre code json serait comme ci-dessous.

"paths": {
    "/getPet/{petId}": {
      "get": {
        "description": "",
        "operationId": "",
        "tags": [],
        "parameters": [],
        "requestBody": {},
        "responses": {
          "511": {}
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/petId"
        }
      ]
    }
  },