Présentation d'OpenAPI

API Gateway accepte les API décrites dans les versions compatibles de la spécification OpenAPI.

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.

Versions OpenAPI compatibles

API Gateway est compatible avec les versions OpenAPI suivantes :

  1. OpenAPI 2.0 (anciennement Swagger)
  2. OpenAPI 3.0.x

Les spécifications officielles de chaque version sont disponibles sur le site de l'OpenAPI Initiative.

Compatibilité avec les versions de correctif

La spécification OpenAPI indique que les versions correctives (par exemple, 3.0.1, 3.0.2) n'introduisent que des corrections ou des clarifications, et n'ajoutent pas de nouvelles fonctionnalités. Par conséquent, API Gateway est compatible avec toutes les versions correctives de la version 3.0.

Terminologie

Dans la documentation API Gateway, OpenAPI 3.x fait référence à toutes les versions OpenAPI 3 compatibles, comme décrit dans Versions OpenAPI compatibles.

Avantages

L'un des principaux avantages présentés par OpenAPI réside dans la documentation. Une fois que vous disposez d'un document OpenAPI qui décrit votre API, vous pouvez générer une documentation de référence pour 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.

La structure de votre document OpenAPI dépend de la version d'OpenAPI que vous utilisez. Les exemples suivants décrivent la structure d'OpenAPI 2.0 et OpenAPI 3.x.

OpenAPI 2.0

Si vous débutez avec OpenAPI, consultez la page Structure Swagger basique, 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."

OpenAPI 3.x

Si vous débutez avec OpenAPI, consultez la page Structure Swagger basique, qui fournit un exemple de document OpenAPI et explique chaque section du fichier. L'exemple suivant illustre cette structure de base :

openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Get the name of an airport from its three-letter IATA code
  version: 1.0.0
x-google-api-management:
  backend:
    BACKEND_NAME
      address: https://BACKEND_URL/airportNameGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
x-google-backend: BACKEND_NAME
paths:
  /airportName:
    get:
      summary: Get the airport name for a given IATA code
      operationId: airportName
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string
      parameters:
        - name: iataCode
          in: query
          required: true
          schema:
            type: string

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, des projets Open Source pour Jersey et Spring peuvent générer un document OpenAPI à partir d'annotations. Un plug-in Maven est également disponible. OpenAPI.Tools peut être un projet intéressant pour les développeurs Python et Node.

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

Étapes suivantes