OpenAPI 總覽

API Gateway 支援使用 OpenAPI 規範 2.0 版說明的 API。您可以使用任何公開 REST 架構 (如 Django 或 Jersey) 來實作 API。

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

優點

使用 OpenAPI 的主要好處之一是可以產生說明文件。一旦您有說明 API 的 OpenAPI 文件，就能輕鬆產生 API 的參考說明文件。

使用 OpenAPI 還有其他好處。例如，您可以：

  • 產生數十種語言的用戶端程式庫
  • 產生伺服器存根
  • 使用專案驗證符合性並產生範例

OpenAPI 文件的基本結構

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

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

如果您是第一次使用 OpenAPI，請瀏覽 Swagger 基本結構網站。此網站提供 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.yaml 檔案設定下列項目：

產生 OpenAPI 文件

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

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

後續步驟