Présentation d'OpenAPI

Cloud Endpoints est compatible avec les API décrites dans la version 2.0 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.

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, il est facile de générer une documentation de référence pour votre API. Consultez la section Portail Cloud Endpoints pour plus d'informations.

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.

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. Le document OpenAPI du guide de démarrage de Endpoints illustre cette structure de base :

    swagger: "2.0"
    info:
      title: "Airport Codes"
      description: "Get the name of an airport from its three-letter IATA code."
      version: "1.0.0"
    # This field will be replaced by the deploy_api.sh script.
    host: "YOUR-PROJECT-ID.appspot.com"
    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."

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