Vista geral da OpenAPI

O Cloud Endpoints suporta APIs descritas através da versão 2.0 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 JSON ou 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.
  • Gerar 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.

Se não conhece a OpenAPI, consulte o Website Estrutura básica do Swagger, que fornece um exemplo de documento OpenAPI (também conhecido como especificação do Swagger) e explica brevemente cada secção do ficheiro. O documento OpenAPI do início rápido dos Endpoints ilustra 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, o ficheiro openapi.yaml do código de exemplo usado nos tutoriais ilustra o seguinte:

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 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 utilizadores do Python, o flask-swagger pode ser um projeto interessante e o swagger-node-express para programadores do Node.

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

O que se segue?