Présentation d'OpenAPI

API Gateway accepte les API décrites à l'aide de la spécification OpenAPI, 2,0. Votre API peut être mise en œuvre à l'aide de tout framework REST accessible au public, tel que Django ou Jersey.

Vous devez décrire votre API dans un fichier YAML, appelé document OpenAPI. Cette page décrit certains des avantages liés à l'utilisation d'OpenAPI, présente un document OpenAPI de base et fournit des informations supplémentaires pour vous aider à démarrer avec OpenAPI.

Avantages

L'un des principaux avantages d'OpenAPI concerne la documentation. une fois que vous un document OpenAPI décrivant votre API, il est facile de générer de référence de votre API.

Il existe d'autres avantages à utiliser OpenAPI. Par exemple, vous pouvez :

  • Générer des bibliothèques clientes dans des dizaines de langues.
  • Générer des stubs de serveur.
  • utiliser des projets pour vérifier votre conformité et pour générer des exemples.

Structure de base d'un document OpenAPI

Un document OpenAPI décrit la surface de votre API REST et définit des informations telles que :

  • le nom et la description de l'API ;
  • les points de terminaison individuels (chemins) dans l'API ;
  • la manière dont les appelants sont authentifiés.

Si vous débutez avec OpenAPI, consultez le Structure de base Swagger qui fournit un exemple de document OpenAPI (également appelé spécification Swagger) et explique brièvement chaque section du fichier. L'exemple suivant illustre cette structure de base :

    swagger: "2.0"
    info:
      title: API_ID optional-string
      description: "Get the name of an airport from its three-letter IATA code."
      version: "1.0.0"
    host: DNS_NAME_OF_DEPLOYED_API
    schemes:
      - "https"
    paths:
      "/airportName":
        get:
          description: "Get the airport name for a given IATA code."
          operationId: "airportName"
          parameters:
            -
              name: iataCode
              in: query
              required: true
              type: string
          responses:
            200:
              description: "Success."
              schema:
                type: string
            400:
              description: "The IATA code is invalid or missing."

En plus de la structure de base, utilisez le fichier openapi.yaml pour configurer les éléments suivants :

Générer un document OpenAPI

Selon la langue utilisée, vous pourrez peut-être générer un document OpenAPI. En Java, il existe des projets Open Source Jersey et Spring capable de générer un document OpenAPI à partir d'annotations. Un plug-in Maven est également disponible. Pour les développeurs Python et Node, OpenAPI.Tools peut être un projet intéressant.

La communauté OpenAPI développe continuellement des outils d'aide à la composition (et, pour certaines langues, à la génération automatique) de documents OpenAPI. Consultez le Spécification OpenAPI pour en savoir plus.

Étape suivante