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 em usar a OpenAPI. Por exemplo, você pode:
- 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_ID optional-string description: "Get the name of an airport from its three-letter IATA code." version: "1.0.0" host: DNS_NAME_OF_DEPLOYED_API schemes: - "https" paths: "/airportName": get: description: "Get the airport name for a given IATA code." operationId: "airportName" parameters: - name: iataCode in: query required: true type: string responses: 200: description: "Success." schema: type: string 400: 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;
- diversos esquemas de segurança para realizar autenticação;
- Extensões da OpenAPI
Como gerar um documento do OpenAPI
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 de Python e Node, 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.