Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Visão geral da OpenAPI
O gateway de API é compatível com as APIs descritas com a especificação OpenAPI, versão 2.0.
É possível implementar a API usando qualquer framework REST de acesso público como Django ou Jersey.
Você descreve a API em um arquivo YAML ou chamado de documento da OpenAPI. Nesta página, você encontra os benefícios do uso da OpenAPI, um documento básico sobre ela e outras informações para começar a usá-la.
Vantagens
Um dos principais benefícios de usar o OpenAPI é a documentação; Quando você tem um documento da OpenAPI que descreve a API, é fácil gerar documentação de referência para a API.
Há outros benefícios do uso da OpenAPI. Por exemplo:
Gerar bibliotecas clientes em dezenas de linguagens.
Gerar stubs de servidor.
Usar projetos para verificar a conformidade e gerar amostras.
Estrutura básica de um documento do OpenAPI
O documento do OpenAPI descreve a superfície da API REST e define informações como:
Nome e descrição da API;
pontos de extremidade individuais (caminhos) na API;
como os chamadores são autenticados
Se você não conhece o OpenAPI, confira o site da
estrutura básica do Swagger, que fornece um documento de amostra do OpenAPI (também chamado de
especificação do Swagger) e explica brevemente cada seção do arquivo.
O exemplo a seguir ilustra essa estrutura 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."
Além da estrutura básica, use o arquivo openapi.yaml para configurar:
O campo title com o nome da API e um optional-string com uma breve descrição.
como configurar um caminho para usar uma chave de API;
Dependendo da linguagem que você usa, é possível gerar um documento do OpenAPI. No Java, há projetos de código aberto para
Jersey
e Spring
que geram um documento do OpenAPI a partir das anotações. Também há um plug-in Maven.
Para desenvolvedores do Python e do Node, o OpenAPI.Tools
pode ser um projeto interessante.
A comunidade do OpenAPI está sempre desenvolvendo ferramentas para ajudar na escrita e, em algumas linguagens, na geração automática dos documentos do OpenAPI. Consulte a
Especificação OpenAPI
para mais informações.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 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)"]]
