您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
在「設計」階段,您可以定義 API 的需求。身為 API 設計人員,您會規劃要向消費者呈現的服務,並設計 API 來存取這些服務。建立下列其中一種文件來擷取 API 需求:
- OpenAPI 文件
- GraphQL 結構定義
以下各節將進一步說明 OpenAPI 和 GraphQL 文件,以及它們在 API 生命週期中扮演的角色。如需兩種 API 設計選項的比較,請參閱這篇網誌文章中的 REST 和 GraphQL。
OpenAPI 規格是什麼?
「OpenAPI 倡議計畫 (OAI) 著重於根據 Swagger 規範,建立、改進和宣傳供應商中立的 API 說明格式。」如要進一步瞭解 OpenAPI 計畫,請參閱 https://openapis.org。
OpenAPI 文件使用標準格式來描述符合 REST 樣式的 API。以 JSON 或 YAML 格式編寫的 OpenAPI 文件不僅可供機器讀取,也能讓使用者輕鬆閱讀及理解。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 結構定義,可定義資料進入點 (查詢類型)、可用的寫入作業 (Mutation 類型) 和資料類型。
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 Proxy 和任何公開資源資源的 API 產品,然後重新產生 API 參考說明文件,反映文件中所做的變更。
- 如果刪除文件,您必須手動刪除相關構件 (包括 API Proxy 和編輯任何 API 產品),才能刪除相關資源。此外,您也必須重新產生 API 參考說明文件,確實反映文件移除及其資源。
如果我透過 OpenAPI 文件建立 API Proxy,會有什麼影響?
在 Edge 中,您可以透過 OpenAPI 文件建立 API Proxy。只要按幾下滑鼠,就能設定 API Proxy,其中包含系統自動產生的路徑、參數、條件式流程和目標端點。接著,您可以新增 OAuth 安全性、頻率限制和快取等功能。
您可以按照下列各節的說明,透過 OpenAPI 文件建立 API Proxy:
- 透過規格清單,按照在規格清單中的規格建立 API Proxy 一文所述的方式建立。注意:傳統版 Edge 不提供規格清單。
- 透過 API Proxy 管理員叫用建構 Proxy 精靈,並選擇從 OpenAPI 文件建立 API Proxy,如使用 OpenAPI 規格產生 Proxy 一節所述。
發布 API 時,您可以拍攝 OpenAPI 文件的快照,藉此產生 API 參考說明文件。這個快照代表規格儲存庫中說明文件的特定修訂版本。