Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Vista geral da OpenAPI
O API Gateway suporta APIs descritas através da especificação OpenAPI, versão 2.0.
Pode implementar a sua API através de qualquer framework REST disponível publicamente, como o Django ou o Jersey.
Descreve a sua API num ficheiro YAML denominado documento OpenAPI. Esta página descreve algumas das vantagens da utilização da OpenAPI,
mostra um documento OpenAPI básico e fornece informações adicionais
para ajudar a começar a usar a OpenAPI.
Vantagens
Uma das principais vantagens da utilização da OpenAPI é a documentação. Depois de ter um documento OpenAPI que descreve a sua API, é fácil gerar documentação de referência para a mesma.
Existem outras vantagens na utilização da OpenAPI. Por exemplo, pode:
Gere bibliotecas cliente em dezenas de idiomas
Gere stubs do servidor
Use projetos para validar a sua conformidade e gerar amostras
Estrutura básica de um documento OpenAPI
Um documento OpenAPI descreve a superfície da sua API REST e define informações como:
O nome e a descrição da API
Os pontos finais individuais (caminhos) na API
Como os autores das chamadas são autenticados
Se não conhece a OpenAPI, consulte o Website da
estrutura básica do Swagger, que fornece um documento OpenAPI de exemplo (também denominado
especificação Swagger) e explica brevemente cada secção do ficheiro.
O exemplo seguinte ilustra esta 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 ficheiro openapi.yaml para configurar:
O campo title com o nome da sua API e um optional-string
com uma breve descrição.
Como configurar um caminho para usar uma chave da API
Consoante o idioma que estiver a usar, pode conseguir gerar um documento OpenAPI. Em Java, existem projetos de código aberto para Jersey e Spring que podem gerar um documento OpenAPI a partir de anotações. Também existe um
plug-in do Maven.
Para programadores de Python e Node, o OpenAPI.Tools
pode ser um projeto interessante.
A comunidade OpenAPI está a desenvolver continuamente ferramentas para ajudar na composição (e, para alguns idiomas, na geração automática) de documentos 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-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)"]]
