Visão geral da OpenAPI

O Cloud Endpoints é compatível com as APIs descritas com a versão 2.0 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 JSON ou YAML 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.

Outros benefícios do uso da OpenAPI são:

  • 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 autores de chamadas 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 e explica rapidamente cada seção do arquivo. No documento do OpenAPI no Guia de início rápido do Endpoints, ilustramos esta estrutura básica:

    swagger: "2.0"
    info:
      title: "Airport Codes"
      description: "Get the name of an airport from its three-letter IATA code."
      version: "1.0.0"
    # This field will be replaced by the deploy_api.sh script.
    host: "YOUR-PROJECT-ID.appspot.com"
    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, no arquivo openapi.yaml do código de amostra usado nos tutoriais, é demonstrado:

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 usuários do Python, o flask-swagger é um projeto interessante e, para desenvolvedores do Node, há o swagger-node-express.

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 o site do Swagger para ver uma lista completa de ferramentas e integrações.

A seguir