Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
Panoramica di OpenAPI
API Gateway supporta le API descritte utilizzando la specifica OpenAPI, versione
2.0.
L'API può essere implementata utilizzando qualsiasi framework REST disponibile pubblicamente, ad esempio Django o Jersey.
Descrivi la tua API in un file YAML chiamato documento OpenAPI. Questa pagina descrive alcuni dei vantaggi dell'utilizzo di OpenAPI, mostra un documento OpenAPI di base e fornisce informazioni aggiuntive per aiutarti a iniziare a utilizzare OpenAPI.
Vantaggi
Uno dei principali vantaggi dell'utilizzo di OpenAPI è la documentazione. Una volta che hai un documento OpenAPI che descrive la tua API, è facile generare la documentazione di riferimento per la tua API.
L'utilizzo di OpenAPI offre altri vantaggi. Ad esempio, puoi:
Generare librerie client in dozzine di lingue
Genera stub del server
Utilizzare i progetti per verificare la conformità e generare i sample
Struttura di base di un documento OpenAPI
Un documento OpenAPI descrive l'interfaccia della tua API REST e definisce informazioni quali:
Il nome e la descrizione dell'API
I singoli endpoint (percorsi) nell'API
Come vengono autenticati i chiamanti
Se non hai mai utilizzato OpenAPI, dai un'occhiata al sito web Struttura di base di Swagger, che fornisce un documento OpenAPI di esempio (chiamato anche specifica Swagger) e spiega brevemente ogni sezione del file.
L'esempio seguente illustra questa struttura di base:
swagger:"2.0"info:title:API_IDoptional-stringdescription:"Get the name of an airport from its three-letter IATA code."version:"1.0.0"host:DNS_NAME_OF_DEPLOYED_APIschemes:-"https"paths:"/airportName":get:description:"Get the airport name for a given IATA code."operationId:"airportName"parameters:-name:iataCodein:queryrequired:truetype:stringresponses:200:description:"Success."schema:type:string400:description:"The IATA code is invalid or missing."
Oltre alla struttura di base, utilizza il file openapi.yaml per configurare:
Il campo title con il nome dell'API e un optional-string
con una breve descrizione.
Come configurare un percorso per utilizzare una chiave API
A seconda della lingua che utilizzi, potresti essere in grado di generare un
documento OpenAPI. In Java, esistono progetti open source sia per Jersey sia per Spring che possono generare un documento OpenAPI dalle annotazioni. È disponibile anche un
plug-in Maven.
Per gli sviluppatori di Python e Node, OpenAPI.Tools potrebbe essere un progetto interessante.
La community OpenAPI sviluppa continuamente strumenti per facilitare la composizione
(e, per alcune lingue, la generazione automatica) dei documenti OpenAPI. Per saperne di più, consulta la specifica OpenAPI.
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Difficile da capire","hardToUnderstand","thumb-down"],["Informazioni o codice di esempio errati","incorrectInformationOrSampleCode","thumb-down"],["Mancano le informazioni o gli esempi di cui ho bisogno","missingTheInformationSamplesINeed","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 2025-09-03 UTC."],[[["\u003cp\u003eAPI Gateway supports APIs described using the OpenAPI specification, specifically version 2.0, allowing implementation with any public REST framework like Django or Jersey.\u003c/p\u003e\n"],["\u003cp\u003eOpenAPI documents, written in YAML, define the structure and surface of a REST API, including its name, description, endpoints, and authentication methods.\u003c/p\u003e\n"],["\u003cp\u003eUsing OpenAPI provides significant benefits, such as generating API reference documentation, client libraries, server stubs, and verification tools.\u003c/p\u003e\n"],["\u003cp\u003eAn OpenAPI document's basic structure includes defining the API's title, description, version, host, schemes, and paths, with an example provided for airport name retrieval.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eopenapi.yaml\u003c/code\u003e file can be used to configure various aspects of the API such as title, optional description, API key usage, security schemes, and OpenAPI extensions.\u003c/p\u003e\n"]]],[],null,["# OpenAPI overview\n================\n\nAPI Gateway supports APIs that are described using the OpenAPI specification, version\n[2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md).\nYour API can be implemented using any publicly available REST framework such as\n[Django](https://www.djangoproject.com/) or [Jersey](https://jersey.github.io/).\n\nYou describe your API in a `YAML` file referred to as an *OpenAPI\ndocument*. This page describes some of the benefits to using OpenAPI,\nshows a basic OpenAPI document, and provides additional information\nto help you get started with OpenAPI.\n| **Note:** For API Gateway, you use the same Open API syntax for defining your APIs as described in the Cloud Endpoints doc at [OpenAPI overview](/endpoints/docs/openapi/openapi-overview).\n\nBenefits\n--------\n\nOne of the primary benefits to using OpenAPI is for documentation; once you\nhave an OpenAPI document that describes your API, it is easy to generate\nreference documentation for your API.\n\nThere are other benefits to using OpenAPI. For example, you can:\n\n- Generate client libraries in dozens of languages\n- Generate server stubs\n- Use projects to verify your conformance and to generate samples\n\nBasic structure of an OpenAPI document\n--------------------------------------\n\nAn OpenAPI document describes the surface of your REST API, and defines information such as:\n\n- The name and description of the API\n- The individual endpoints (paths) in the API\n- How the callers are authenticated\n\nIf you are new to OpenAPI, take a look at the\n[Swagger basic structure](https://swagger.io/docs/specification/2-0/basic-structure/)\nwebsite, which provides a sample OpenAPI document (also referred to as a\nSwagger specification) and briefly explains each section of the file.\nThe following example illustrates this basic structure: \n\n```carbon\n swagger: \"2.0\"\n info:\n title: API_ID optional-string\n description: \"Get the name of an airport from its three-letter IATA code.\"\n version: \"1.0.0\"\n host: DNS_NAME_OF_DEPLOYED_API\n schemes:\n - \"https\"\n paths:\n \"/airportName\":\n get:\n description: \"Get the airport name for a given IATA code.\"\n operationId: \"airportName\"\n parameters:\n -\n name: iataCode\n in: query\n required: true\n type: string\n responses:\n 200:\n description: \"Success.\"\n schema:\n type: string\n 400:\n description: \"The IATA code is invalid or missing.\"\n```\n| **Note:** For API Gateway, use of the `host` property in your API definition is optional. You can either omit the `host` property entirely from the API definition or set it to the DNS name of the deployed API. API providers often set it to the DNS name when sharing the OpenAPI Spec with their API consumers. Do not set the `host` property to **null** or an empty value, as this will result in an error.\n\nIn addition to the basic structure, use the `openapi.yaml` file to configure:\n\n- The `title` field with the name of your API and an \u003cvar translate=\"no\"\u003eoptional-string\u003c/var\u003e with a brief description.\n- How to configure a path to use an [API key](/api-gateway/docs/authentication-method)\n- Various [security schemes](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#securitySchemeObject) for authentication\n- [OpenAPI extensions](/endpoints/docs/openapi/openapi-extensions)\n\nGenerating an OpenAPI document\n------------------------------\n\nDepending on what language you are using, you might be able to generate an\nOpenAPI document. In Java, there are open source projects for both\n[Jersey](https://jersey.github.io/)\nand [Spring](https://github.com/springfox/springfox)\nthat can generate an OpenAPI document from annotations. There is also a\n[Maven plugin](http://kongchen.github.io/swagger-maven-plugin/).\nFor Python and Node developers, [OpenAPI.Tools](https://openapi.tools/)\nmight be an interesting project.\n\nThe OpenAPI community is continually developing tools to help in the composition\n(and, for some languages, automatic generation) of OpenAPI documents. See the\n[The OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification)\nfor more.\n\nWhat's next\n-----------\n\n| **Note:** Because you use the same Open API syntax for the API Gateway as you used for Cloud Endpoints, these links refer to locations in the [Cloud Endpoints](/endpoints/docs/openapi/openapi-overview) documentation.\n\n- [OpenAPI extensions](/endpoints/docs/openapi/openapi-extensions)\n- [Unsupported OpenAPI features](/endpoints/docs/openapi/openapi-limitations)"]]
