Vista geral da OpenAPI

O Cloud Endpoints suporta APIs descritas através de versões compatíveis 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.

Versões da OpenAPI compatíveis

O Cloud Endpoints suporta as seguintes versões da OpenAPI:

  1. OpenAPI 2.0 (anteriormente Swagger)
  2. 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 Cloud Endpoints suporta todas as versões de patch da versão 3.0.

Terminologia

Ao longo da documentação do Cloud Endpoints, OpenAPI 3.x refere-se a todas as versões suportadas do OpenAPI 3.

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.
  • 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.

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 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 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: API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
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 especificação OpenAPI, 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
servers:
  - url: https://API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
    x-google-endpoint: {}
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

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 de Python, o flask-swagger pode ser um projeto interessante e o swagger-node-express para programadores de 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?