Visão geral da OpenAPI

O Cloud Endpoints é compatível com APIs descritas usando versões compatíveis 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.

Versões compatíveis da OpenAPI

O Cloud Endpoints é compatível com as seguintes versões do OpenAPI:

  1. OpenAPI 2.0 (antigo Swagger)
  2. OpenAPI 3.0.x

As especificações oficiais de cada versão estão disponíveis na OpenAPI Initiative (link em inglês).

Suporte à versão de patch

A especificação OpenAPI indica que as versões de patch (por exemplo, 3.0.1, 3.0.2) apenas introduzem correções ou esclarecimentos e não adicionam novos recursos. Como resultado, o Cloud Endpoints é compatível com todas as versões de patch da 3.0.

Terminologia

Em toda a documentação do Cloud Endpoints, OpenAPI 3.x se refere a todas as versões compatíveis da OpenAPI 3.

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

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 chamadores são autenticados

A estrutura do documento OpenAPI depende da versão usada. Os exemplos a seguir descrevem a estrutura do OpenAPI 2.0 e do OpenAPI 3.x.

OpenAPI 2.0

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. 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: 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 você não conhece o OpenAPI, confira a especificação OpenAPI, que fornece um documento de amostra do OpenAPI e explica cada seção do arquivo.

O exemplo a seguir ilustra essa 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, 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