Esta página foi traduzida pela API Cloud Translation.

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:

OpenAPI 2.0 (anteriormente Swagger)
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 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

Nota: para o API Gateway, a utilização de host ou servers.url na definição da API é opcional. Pode omitir este elemento da definição OpenAPI 2.0 ou OpenAPI 3.x, ou defini-lo como o nome DNS da API implementada. Os fornecedores de APIs definem-no frequentemente como o nome DNS quando partilham a descrição da OpenAPI com os respetivos consumidores de APIs. Não defina a propriedade host ou servers.url como nula ou um valor vazio, uma vez que isto resulta num erro.

Para mais informações, consulte o artigo Servidores.

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

O campo title com o nome da sua API e um optional-string com uma breve descrição.
Um caminho para usar uma chave da API.
Vários esquemas de segurança para OpenAPI 2.0 ou OpenAPI 3.x para autenticação.
Extensões para OpenAPI 2.0 e OpenAPI 3.x.

Gere um documento OpenAPI

Consoante o idioma que estiver a usar, pode conseguir gerar um documento OpenAPI. Em Java, existem projetos de código aberto para o Jersey e o 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.