Visão geral da OpenAPI

O gateway de API é compatível com as APIs descritas usando as 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 optional-string
  description: Get the name of an airport from its three-letter IATA code
  version: 1.0.0
x-google-api-management:
  backend:
    BACKEND_NAME
      address: https://BACKEND_URL/airportNameGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
x-google-backend: BACKEND_NAME
paths:
  /airportName:
    get:
      summary: Get the airport name for a given IATA code
      operationId: airportName
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string
      parameters:
        - name: iataCode
          in: query
          required: true
          schema:
            type: string

Além da estrutura básica, use o arquivo openapi.yaml para configurar:

Gerar um documento da 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 do Python e do Node, o TextView.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.

A seguir