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 :
- Le champ
title
avec le nom de votre API et un optional-string avec une brève description. - Comment configurer un chemin pour utiliser une clé API
- Différents schémas de sécurité pour l'authentification
- les extensions OpenAPI.
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.