Organiza tus páginas con colecciones
Guarda y categoriza el contenido según tus preferencias.
OpenAPI | gRPC
Cloud Endpoints es compatible con las API que se describen si se usa la versión 2.0 de la especificación de OpenAPI.
Puedes implementar tu API con cualquier marco de trabajo REST disponible públicamente, como Django o Jersey.
Describes tu API en un archivo JSON o YAML al que se hace referencia como un documento de OpenAPI. En esta página, se describen algunos de los beneficios del uso de OpenAPI, se muestra un documento básico de OpenAPI y se proporciona información adicional para ayudarte a comenzar con OpenAPI.
Ventajas
Uno de los beneficios principales del uso de OpenAPI es para la documentación; una vez que tienes un documento de OpenAPI que describe tu API, es fácil generar la documentación de referencia para tu API.
El uso de OpenAPI tiene otros beneficios. Por ejemplo, puedes hacer lo siguiente:
Generar bibliotecas cliente en decenas de lenguajes
Generar stubs de servidores.
Usar proyectos para verificar tu conformidad y generar muestras.
Estructura básica de un documento de OpenAPI
Un documento de OpenAPI describe la superficie de tu API de REST y define información como la siguiente:
El nombre y la descripción de la API
Los extremos (rutas) individuales en la API
Cómo se autentican los emisores
Si aún no te familiarizaste con OpenAPI, consulta el sitio web Estructura básica de Swagger, que proporciona un documento de OpenAPI de muestra y explica brevemente cada sección del archivo.
El documento de OpenAPI de la guía de inicio rápido de Endpoints ilustra esta estructura básica:
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."
Además de la estructura básica, en el archivo openapi.yaml del código de muestra utilizado en los instructivos, se ilustra lo siguiente:
Cómo configurar una ruta para usar una clave de API
Según el lenguaje que utilizas, es posible que puedas generar un documento de OpenAPI. En Java, existen proyectos de código abierto para Jersey y Spring que pueden generar un documento de OpenAPI desde anotaciones. También existe un complemento de Maven.
Para los usuarios de Python, flask-swagger puede ser un proyecto interesante, al igual que swagger-node-express para los desarrolladores de Node.
La comunidad de OpenAPI está desarrollando continuamente herramientas de ayuda para la composición (y, en el caso de algunos lenguajes, la generación automática) de documentos de OpenAPI. Consulta el sitio web de Swagger para obtener una lista completa de integraciones y herramientas.
[[["Fácil de comprender","easyToUnderstand","thumb-up"],["Resolvió mi problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Información o código de muestra incorrectos","incorrectInformationOrSampleCode","thumb-down"],["Faltan la información o los ejemplos que necesito","missingTheInformationSamplesINeed","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 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)"]]
