OpenAPI 總覽

API Gateway 支援使用 支援版本的 OpenAPI 規格說明的 API。

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

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

支援的 OpenAPI 版本

API Gateway 支援下列 OpenAPI 版本：

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

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

支援修補程式版本

OpenAPI 規格指出，修補程式版本 (例如 3.0.1、3.0.2) 只會修正錯誤或提供說明，不會新增功能。因此，API Gateway 支援 3.0 的所有修補程式版本。

術語

在 API Gateway 說明文件中，「OpenAPI 3.x」是指所有支援的 OpenAPI 3 版本，如「支援的 OpenAPI 版本」一文所述。

優點

使用 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: DNS_NAME_OF_DEPLOYED_API
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，請瀏覽 Swagger Basic Structure，此網站提供 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
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

除了基本架構之外，您也可以使用 openapi.yaml 檔案設定以下項目：

產生 OpenAPI 文件

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

OpenAPI 社群持續開發新工具，協助撰寫 OpenAPI 文件，還能為某些語言自動產生這類文件。詳情請參閱「OpenAPI 規範」。

後續步驟