OpenAPI 總覽

Cloud Endpoints 支援使用 支援版本的 OpenAPI 規範說明的 API。

您可以使用任何開放給大眾使用的 REST 架構 (如 Django 或 Jersey) 來實作 API。

您可以在 JSON 或 YAML 檔案 (稱為「OpenAPI 文件」) 中說明 API。本頁面說明使用 OpenAPI 的優點、示範基本的 OpenAPI 文件，同時也提供能協助您開始使用 OpenAPI 的其他資訊。

支援的 OpenAPI 版本

Cloud Endpoints 支援下列 OpenAPI 版本：

  1. OpenAPI 2.0 (前身為 Swagger)
  2. OpenAPI 3.0.x
  3. OpenAPI 3.1.x

如要查看各版本的正式規格，請前往 OpenAPI Initiative。

支援修補程式版本

OpenAPI 規格指出，修補程式版本 (例如 3.0.1、3.0.2) 只會推出修正或說明，不會新增功能。因此，Cloud Endpoints 支援 3.0 和 3.1 的所有修補程式版本。

術語

在 Cloud Endpoints 說明文件中，OpenAPI 3.x 是指所有支援的 OpenAPI 3 版本。

優點

使用 OpenAPI 的主要優點之一是方便製作說明文件；只要有說明 API 的 OpenAPI 文件，就能產生 API 的參考說明文件。

使用 OpenAPI 還有其他優點。例如，您可以：

  • 產生使用數十種語言的用戶端程式庫。
  • 產生伺服器虛設常式。
  • 使用專案來驗證符合程度和產生範例。

OpenAPI 文件的基本結構

OpenAPI 文件說明您 REST API 的介面，並定義以下資訊：

  • API 名稱和說明。
  • API 中的各個端點 (路徑)。
  • 呼叫端驗證方式。

OpenAPI 文件的結構取決於您使用的 OpenAPI 版本。下列範例說明 OpenAPI 2.0 和 OpenAPI 3.x 的結構。

OpenAPI 2.0

如果您是第一次使用 OpenAPI，請瀏覽 Swagger Basic Structure 網站。此網站提供 OpenAPI 文件範本 (也就是 Swagger 規範)，並簡要說明檔案中的每個區段。下列範例說明這項基本結構：

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

如果您是第一次使用 OpenAPI，請瀏覽 OpenAPI 規範。此網站提供 OpenAPI 文件範本，並說明檔案中的每個區段。

以下範例說明這個基本結構：

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:
  backends:
    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

除了基本架構之外，本教學課程所用的範例程式碼 openapi.yaml 檔案也說明以下事項：

產生 OpenAPI 文件

視您使用的語言而定，您或許能產生一份 OpenAPI 文件。Java 提供同時適用於 Jersey 和 Spring 的開放原始碼專案，可利用註解產生 OpenAPI 文件。此外，Java 也提供一款 Maven 外掛程式。Python 使用者可能會對 flask-swagger 專案感興趣，而 swagger-node-express 則是適用於 Node 開發人員。

OpenAPI 社群持續開發新工具，協助撰寫 OpenAPI 文件，還能為某些語言自動產生這類文件。如需完整的工具及整合功能清單，請參閱 Swagger 網站。

後續步驟