Présentation d'OpenAPI

Cloud Endpoints 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 JSON ou 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

Cloud Endpoints est compatible avec les versions suivantes d'OpenAPI :

  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, Cloud Endpoints est compatible avec toutes les versions correctives de la version 3.0.

Terminologie

Dans la documentation Cloud Endpoints, OpenAPI 3.x fait référence à toutes les versions 3 d'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. Vous pouvez, par exemple :

  • 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 le site Web Swagger Basic Structure (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: API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
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 spécification OpenAPI, 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
servers:
  - url: https://API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
    x-google-endpoint: {}
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

Outre la structure de base, le fichier openapi.yaml de l'exemple de code utilisé dans les tutoriels explique :

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. flask-swagger peut être un projet intéressant pour les utilisateurs de Python, et swagger-node-express pour les développeurs 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. Consultez le site Web Swagger pour obtenir une liste complète des outils et des intégrations.

Étapes suivantes