Visão geral da OpenAPI

O gateway de API é compatível com as APIs descritas usando versões compatíveis da especificação OpenAPI.

É 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.

Versões compatíveis da OpenAPI

O gateway de API é compatível com as seguintes versões da OpenAPI:

  1. OpenAPI 2.0 (antigo Swagger)
  2. OpenAPI 3.0.x

As especificações oficiais de cada versão estão disponíveis na OpenAPI Initiative (link em inglês).

Suporte à versão de patch

A especificação OpenAPI indica que as versões de patch (por exemplo, 3.0.1, 3.0.2) apenas introduzem correções ou esclarecimentos e não adicionam novos recursos. Como resultado, o API Gateway é compatível com todas as versões de patch do 3.0.

Terminologia

Em toda a documentação do API Gateway, OpenAPI 3.x se refere a todas as versões compatíveis do OpenAPI 3, conforme descrito em Versões compatíveis do OpenAPI.

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 ela.

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

A estrutura do documento OpenAPI depende da versão usada. Os exemplos a seguir descrevem a estrutura do OpenAPI 2.0 e do OpenAPI 3.x.

OpenAPI 2.0

Se você não conhece o OpenAPI, confira a estrutura básica do Swagger, que fornece um documento de amostra do OpenAPI e explica rapidamente 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."

OpenAPI 3.x

Se você não conhece o OpenAPI, confira a estrutura básica do Swagger, que fornece um documento de amostra do OpenAPI e explica cada seção do arquivo. O exemplo a seguir ilustra essa estrutura básica:

openapi: 3.0.4
info:
  title: API_ID