Vista geral da OpenAPI

O Gateway da API suporta APIs descritas através de versões suportadas da especificação OpenAPI.

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.

Versões da OpenAPI compatíveis

O API Gateway suporta as seguintes versões da OpenAPI:

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

As especificações oficiais de cada versão estão disponíveis na OpenAPI Initiative.

Suporte da versão de patch

A especificação OpenAPI indica que as versões de patch (por exemplo, 3.0.1 e 3.0.2) apenas introduzem correções ou esclarecimentos e não adicionam novas funcionalidades. Como resultado, o gateway da API suporta todas as versões de patch da versão 3.0.

Terminologia

Ao longo da documentação da API Gateway, OpenAPI 3.x refere-se a todas as versões 3 do OpenAPI suportadas, conforme descrito em Versões do OpenAPI suportadas.

Vantagens

Uma das principais vantagens da utilização da OpenAPI é a documentação. Depois de ter um documento OpenAPI que descreve a sua API, pode 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 exemplos

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

A estrutura do seu documento OpenAPI depende da versão do OpenAPI que usa. Os exemplos seguintes descrevem a estrutura do OpenAPI 2.0 e do OpenAPI 3.x.

OpenAPI 2.0

Se não conhece a OpenAPI, consulte a 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_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 não conhece a OpenAPI, consulte a estrutura básica do Swagger, que fornece um documento OpenAPI de exemplo e explica cada secção do ficheiro. O exemplo seguinte ilustra esta estrutura básica:

openapi: 3.0.4
info:
  title: API_ID