OpenAPI 總覽

Cloud Endpoints 支援使用 OpenAPI 規範 2.0 版說明的 API。您可以使用任何開放給大眾使用的 REST 架構 (如 DjangoJersey) 來實作 API。您可以在 JSONYAML 檔案 (稱為「OpenAPI 文件」) 中說明 API。本頁面說明使用 OpenAPI 的優點、示範基本的 OpenAPI 文件,同時也提供能協助您開始使用 OpenAPI 的其他資訊。

優勢

使用 OpenAPI 的其中一項主要優點在於說明文件;只要有能說明 API 的 OpenAPI 文件,很容易就能產生 API 參考文件。詳情請參閱 Cloud Endpoints 入口網站

使用 OpenAPI 還有其他優點。例如,您可以:

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

OpenAPI 文件的基本結構

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

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

如果您是第一次使用 OpenAPI,請瀏覽 Swagger Basic Structure 網站。此網站提供 OpenAPI 文件範本 (也就是 Swagger 規範),並簡要說明檔案中的每個區段。Endpoints 快速入門導覽課程的 OpenAPI 文件說明以下基本結構:

    swagger: "2.0"
    info:
      title: "Airport Codes"
      description: "Get the name of an airport from its three-letter IATA code."
      version: "1.0.0"
    # This field will be replaced by the deploy_api.sh script.
    host: "YOUR-PROJECT-ID.appspot.com"
    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 提供同時適用於 JerseySpring 的開放原始碼專案,可利用註解產生 OpenAPI 文件。此外,Java 也提供一款 Maven 外掛程式。Python 使用者可能會對 flask-swagger 專案感興趣,而 swagger-node-express 則是適用於 Node 開發人員。

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

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Cloud Endpoints 搭配 OpenAPI
需要協助嗎?請前往我們的支援網頁