Visão geral da OpenAPI

O gateway de API é compatível com as APIs descritas com a especificação OpenAPI, versão 2.0. É 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.

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 a API.

Há outros benefícios do uso da OpenAPI. Por exemplo:

  • 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

Se você não conhece o OpenAPI, confira o site da estrutura básica do Swagger, que fornece um documento de amostra do OpenAPI (também chamado de especificação do Swagger) e explica brevemente 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."

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

Como gerar um documento do 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 OpenAPI.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