Vista geral da OpenAPI

O API Gateway suporta APIs descritas através da especificação OpenAPI, versão 2.0. 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.

Vantagens

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

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

Se não conhece a OpenAPI, consulte o Website da 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."

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

Gerar 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 Jersey e 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.

O que se segue?