Organízate con las colecciones
Guarda y clasifica el contenido según tus preferencias.
Información general sobre OpenAPI
API Gateway admite APIs descritas mediante la especificación de OpenAPI, versión 2.0.
Tu API se puede implementar con cualquier framework REST disponible públicamente, como Django o Jersey.
Describe tu API en un archivo YAML denominado documento de OpenAPI. En esta página se describen algunas de las ventajas de usar OpenAPI, se muestra un documento de OpenAPI básico y se proporciona información adicional para ayudarte a empezar a usar OpenAPI.
Ventajas
Una de las principales ventajas de usar OpenAPI es la documentación. Una vez que tengas un documento de OpenAPI que describa tu API, será fácil generar documentación de referencia para ella.
Usar OpenAPI tiene otras ventajas. Por ejemplo, puedes:
Generar bibliotecas de cliente en decenas de idiomas
Generar stubs de servidor
Usa 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 REST y define información como la siguiente:
El nombre y la descripción de la API
Los endpoints (rutas) individuales de la API
Cómo se autentican las personas que llaman
Si no conoces OpenAPI, consulta el sitio web Estructura básica de Swagger, que proporciona un documento de ejemplo de OpenAPI (también denominado especificación de Swagger) y explica brevemente cada sección del archivo.
En el siguiente ejemplo se muestra esta estructura básica:
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."
Además de la estructura básica, usa el archivo openapi.yaml para configurar lo siguiente:
El campo title con el nombre de tu API y un optional-string
con una breve descripción.
Cómo configurar una ruta para usar una clave de API
En función del idioma que uses, es posible que puedas generar un documento de OpenAPI. En Java, hay proyectos de código abierto para Jersey y Spring que pueden generar un documento de OpenAPI a partir de anotaciones. También hay un plugin de Maven.
Si eres desarrollador de Python y Node, OpenAPI.Tools puede ser un proyecto interesante.
La comunidad de OpenAPI desarrolla continuamente herramientas para ayudar en la composición (y, en algunos idiomas, en la generación automática) de documentos de OpenAPI. Consulta la sección Especificación de OpenAPI para obtener más información.
[[["Es fácil de entender","easyToUnderstand","thumb-up"],["Me ofreció una solución al problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Es difícil de entender","hardToUnderstand","thumb-down"],["La información o el código de muestra no son correctos","incorrectInformationOrSampleCode","thumb-down"],["Me faltan las muestras o la información que necesito","missingTheInformationSamplesINeed","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 2025-08-19 (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)"]]
