本頁適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
在設計階段，您會定義 API 的必要條件。身為 API 設計師，您需要規劃要公開給使用者的服務，並設計用於存取這些服務的 API。您可以建立下列任一文件，擷取 API 需求：
- OpenAPI 文件
- GraphQL 結構定義
以下各節將進一步說明 OpenAPI 和 GraphQL 文件，以及這些文件在 API 生命週期中扮演的角色。如要比較這兩種 API 設計選項，請參閱這篇網誌文章，瞭解 REST 和 GraphQL 的比較。
什麼是 OpenAPI 規範？
「OpenAPI Initiative (OAI) 專注於根據 Swagger 規範建立、改進及推廣供應商中立的 API 說明格式。」如要進一步瞭解 OpenAPI 計畫，請前往 https://openapis.org。
OpenAPI 文件使用標準格式說明 RESTful API。OpenAPI 文件採用 JSON 或 YAML 格式編寫，可供機器讀取，但也便於人類閱讀和理解。OpenAPI 規格可讓您正式說明 API 的元素，例如基本路徑、路徑和動詞、標頭、查詢參數、內容類型、回應模型等等。此外，OpenAPI 文件通常用於產生 API 說明文件。
以下是 OpenAPI 文件的片段，說明 Apigee 的簡易 Hello World 範例。如需更多資訊，請前往 GitHub 查看 OpenAPI 規範。
openapi: 3.0.0
info:
description: OpenAPI Specification for the Apigee mock target service endpoint.
version: 1.0.0
title: Mock Target API
paths:
/:
get:
summary: View personalized greeting
operationId: View a personalized greeting
description: View a personalized greeting for the specified or guest user.
parameters:
- name: user
in: query
description: Your user name.
required: false
schema:
type: string
responses:
"200":
description: Success
/help:
get:
summary: Get help
operationId: Get help
description: View help information about available resources in HTML format.
responses:
"200":
description: Success
...
許多優質的資訊來源都提供 OpenAPI 規格相關資訊。建議您從 OpenAPI Initiative 網站開始著手，這裡有總覽、部落格文章和 OpenAPI 規範的連結。如需結構定義元素和資料類型的詳細說明，請參閱規格。
您可以從 OpenAPI 規格存放區下載許多 JSON 和 YAML 範例 OpenAPI 文件。
什麼是 GraphQL 結構定義？
GraphQL 結構定義會說明 API 中可供用戶端查詢的資料。
使用 GraphQL 的好處包括：
- 單一端點可提供特定作業的所有欄位存取權
- 強大的查詢語言稱為結構定義語言，可讓您精確存取所需資料，避免過度或不足擷取資料
- 並行處理查詢
如要進一步瞭解 GraphQL，請造訪 graphql.org。
以下提供 GraphQL 結構定義範例，其中定義了資料輸入點 (查詢類型)、可用的寫入作業 (變異型類型) 和資料類型。
type Query {
Greeting: String
students: [Student]
}
type Mutation {
createStudent(firstName: String!, lastName: String!): Student!
}
type Subscription {
newStudent: Student!
}
type Student {
Id: ID!
firstName: String!
lastName: String!
password: String!
collegeId: String!
}
您可以查詢 GraphQL 結構定義，以 JSON 酬載的形式傳回所需的確切資料。
如果我修改文件，會發生什麼事？
每份 OpenAPI 或 GraphQL 文件都是整個 API 生命週期中的可靠資料來源。在 API 生命週期的每個階段 (從開發到發布、監控) 都會使用相同的文件。
編輯或刪除文件時，會對後續作業造成影響：
- 如果您要編輯文件，就必須手動編輯相關構件，包括 API 代理程式和任何公開其資源的 API 產品，並重新產生 API 參考說明文件，以反映文件中實作的變更。
- 如果您刪除文件，就必須手動刪除相關構件 (包括 API 代理程式)，並編輯任何 API 產品以刪除相關資源，然後重新產生 API 參考說明文件，以反映已移除文件及其資源。
使用 OpenAPI 文件建立 API Proxy 會發生什麼事？
您可以使用 OpenAPI 文件建立 API Proxy。只要按幾下滑鼠，您就能取得 API 代理程式，其中包含自動產生的路徑、參數、條件流程和目標端點。接著，您可以新增 OAuth 安全性、頻率限制和快取等功能。
您可以使用「建立 Proxy 精靈」建立 OpenAPI 文件的 API Proxy，如「使用 OpenAPI 規格產生 Proxy」一文所述。如要瞭解實作方式，請逐步完成「使用 OpenAPI 規格建立 API Proxy」教學課程。
發布 API 時，您會擷取 OpenAPI 文件的快照，以產生 API 參考說明文件。該快照代表說明文件的特定修訂版本。