Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
OpenAPI | gRPC
Cloud Endpoints supporta le API descritte utilizzando la versione 2.0 della
specifica OpenAPI.
L'API può essere implementata utilizzando qualsiasi framework REST disponibile pubblicamente, ad esempio Django o Jersey.
Descrivi la tua API in un file JSON o 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:
Genera librerie client in dozzine di lingue.
Genera stub server.
Utilizza i progetti per verificare la conformità e generare esempi.
Struttura di base di un documento OpenAPI
Un documento OpenAPI descrive la piattaforma 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.
Il documento OpenAPI della
guida rapida di Endpoints
illustra questa struttura di 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"#Thisfieldwillbereplacedbythedeploy_api.shscript.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:iataCodein:queryrequired:truetype:stringresponses:200:description:"Success."schema:type:string400:description:"The IATA code is invalid or missing."
Oltre alla struttura di base, il file openapi.yaml del codice di esempio utilizzato nei tutorial illustra:
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 utenti di Python, flask-swagger potrebbe essere un progetto interessante, mentre swagger-node-express per gli sviluppatori Node.
La community OpenAPI sviluppa continuamente strumenti per facilitare la composizione
(e, per alcune lingue, la generazione automatica) dei documenti OpenAPI. Per un elenco completo di strumenti e integrazioni, visita il
sito web di Swagger.
[[["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-04 UTC."],[[["\u003cp\u003eOpenAPI is used to describe APIs, and it supports generating reference documentation, client libraries, and server stubs.\u003c/p\u003e\n"],["\u003cp\u003eAn OpenAPI document defines the API's name, description, endpoints, and authentication methods.\u003c/p\u003e\n"],["\u003cp\u003eOpenAPI documents can be written in JSON or YAML, illustrating how to configure API keys and security schemes for authentication.\u003c/p\u003e\n"],["\u003cp\u003eVarious tools and libraries can help compose and automatically generate OpenAPI documents for multiple languages, including Java, Python, and Node.\u003c/p\u003e\n"],["\u003cp\u003eThere are extensions to the OpenAPI specification available for Endpoints APIs, and a few configuration steps to follow.\u003c/p\u003e\n"]]],[],null,["# OpenAPI overview\n\nOpenAPI \\| gRPC\n\n\u003cbr /\u003e\n\nCloud Endpoints supports APIs that are described using version 2.0 of the\n[OpenAPI specification](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/).\nYou describe your API in a `JSON` or `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\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 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\n[surface](/endpoints/docs/openapi/glossary#surface)\nof 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 OpenAPI document from the\n[Endpoints quickstart](/endpoints/docs/deploy-api)\nillustrates this basic structure: \n\n```carbon\n swagger: \"2.0\"\n info:\n title: \"Airport Codes\"\n description: \"Get the name of an airport from its three-letter IATA code.\"\n version: \"1.0.0\"\n # This field will be replaced by the deploy_api.sh script.\n host: \"YOUR-PROJECT-ID.appspot.com\"\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\nIn addition to the basic structure, the `openapi.yaml` file from the sample\ncode used in the [tutorials](/endpoints/docs/openapi/tutorials)\nillustrates:\n\n- How to configure a path to use an [API key](/endpoints/docs/openapi/restricting-api-access-with-api-keys).\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) available for Endpoints APIs.\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\n[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 users, [flask-swagger](https://github.com/gangverk/flask-swagger)\nmight be an interesting project, and\n[swagger-node-express](https://www.npmjs.com/package/swagger-node-express)\nfor Node developers.\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[Swagger website](http://swagger.io/open-source-integrations/)\nfor a complete list of tools and integrations.\n\nWhat's next\n-----------\n\n- [OpenAPI extensions](/endpoints/docs/openapi/openapi-extensions)\n- [Unsupported OpenAPI features](/endpoints/docs/openapi/openapi-limitations)\n- [Configuring Endpoints](/endpoints/docs/openapi/configure-endpoints)\n- [Deploying the Endpoints Configuration](/endpoints/docs/openapi/deploy-endpoints-config)"]]
