您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
SmartDocs 可讓您在 Drupal 7 開發人員入口網站上記錄 API 的 API,使 API 說明文件具備完整的互動性。互動式說明文件意味著入口網站使用者可以:
- 瞭解您的 API
- 將即時要求傳送至您的 API
- 查看 API 傳回的即時回應
只要在您的 API 建立互動式說明文件,入口網站使用者就能輕鬆學習、測試及評估您的 API。
Edge Management API 是符合 REST 樣式的 API,可讓您透過任何 HTTP 用戶端存取 API 服務。Apigee 會使用 SmartDocs 為 Edge Management API 建立互動式說明文件。請參閱這裡的 API 說明文件。
SmartDocs 入口網站範例
如要使用 SmartDocs,您必須具備 Apigee 開發人員服務入口網站。詳情請參閱「建立開發人員入口網站」。
在開發人員入口網站首頁中按一下頂端導覽列的「API」,即可查看 API 說明文件頁面。
入口網站上有兩個 API 記錄:Hello World 和 Pet Store 範例。
Hello World API 是根據模擬目標 OpenAPI 規格 mocktarget.yaml
建立。詳情請參閱 https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi。
「Pet Store Example API」是以經典寵物店試用版建立而成。
探索 Hello World API:
- 按一下「Hello World API」。系統會顯示 Hello World API 摘要頁面:
- 按一下「View API affirmation」,系統會顯示這項資源的 SmartDocs:
- 按一下「傳送這項要求」。
- 查看傳回的回應:
HTTP/1.1 200 OK Connection: keep-alive Content-Length: 18 Content-Type: text/html; charset=utf-8 Date: Tue, 21 Jun 2016 21:49:32 GMT ETag: W/"12-Jb9QP1bUxNSmZkxQGt5KLQ" X-Powered-By: Apigee <H2>I <3 APIs</H2>
- 按一下「要求」分頁標籤查看要求,或按一下「cURL」分頁標籤查看對應的 cURL 呼叫。
如何使用 SmartDocs 記錄 API
SmartDocs 會使用「模型」model呈現您的 API,模型中包含您 API 的所有相關資訊。入口網站會從模型擷取您的 API 相關資訊,以將入口網站上的說明文件頁面顯示為 Drupal 節點,其中每個 Drupal 節點會對應入口網站的說明文件頁面。
以下為使用 SmartDocs 的一般步驟:
- 在入口網站上設定 Drupal SmartDocs 模組。
- 建立 SmartDocs 模型。
- 透過 WADL 檔案、OpenAPI (舊稱 Swagger) 規格或手動新增 API 至模型。
- 以 Drupal 節點集合的形式轉譯模型。每個 Drupal 節點都包含單一 API 的相關資訊。舉例來說,如果 API 中的資源同時支援 POST 和 PUT 要求,SmartDocs 會為 POST 和 PUT 分別建立 Drupal 節點。
- 發布 Drupal 節點。發布後,入口網站使用者就能查看 API 並進行互動。
- 在發布 Drupal 節點前後編輯。您可以使用 Drupal 編輯器,或編輯原始 WADL 檔案或 OpenAPI 規格來編輯 Drupal 節點。編輯 WADL 檔案或 OpenAPI 規範後,請將其匯入模型做為新的修訂版本,然後轉譯並發布變更。
- 啟用 TLS。由於 SmartDocs 向 API 發出要求時,可以將驗證憑證傳送至後端,因此您應在入口網站上啟用 TLS,確保這些憑證安全無虞。在入口網站的實際工作環境和測試環境中,Apigee 會提供提出 https:// 要求所需的 TLS 憑證。不過,在入口網站上線前,您必須取得自己的 TLS 憑證並啟用 TLS。詳情請參閱在入口網站上使用傳輸層安全標準 (TLS)。
關於 SmartDoc 模型和範本
在入口網站建立模型時,模型實際上會儲存在 Edge 機構,而非 Drupal。模型是具有內部名稱的大型 JSON 區塊 (例如「my-smartdocs-api」),並定義 API 的結構。另一方面,入口網站會以 HTML 呈現模型,並提供模型的編輯介面。凡是在入口網站中對 API 所做的更新,都會自動推送回來源模型。
儲存在機構中 |
儲存在 Drupal |
---|---|
模型 |
範本 具備編輯功能的增加節點 |
假設您貴機構中有多個入口網站,例如開發、階段和實際工作環境。在 Pantheon 中,您將入口網站從某個環境移到另一個環境。入口網站的每個執行個體看起來都含有自己的模型,但實際上全都參照了來源模型。如果在開發人員版中編輯 API,模型就會更新,且變更內容會顯示在實際工作環境中。同理,如果您在 dev 中刪除模型,該來源也會一併刪除,且無法再於實際工作環境中使用。
範本可用來控管 SmartDocs 的外觀和風格,而範本 (由控制代碼和 CSS 檔案管理) 則會與每個入口網站執行個體一起儲存。因此,每個入口網站理論上都能針對每個模型使用專屬範本。然而,算繪架構的其中一個便利性,就是系統會自動為各個模型套用預設範本 (Apigee 預設範本或您提供的範本)。
下圖顯示模型與入口網站之間的關係。綠色箭頭顯示自動同步處理作業。
下列 cURL 指令會列出貴機構的所有模型:
curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u
edge_org_admin@example.com
設定 SmartDocs 模組
Apigee 以自訂 Drupal 模組的形式實作 SmartDocs。請按照下列程序設定 SmartDocs 模組。
如何設定 SmartDocs 模組:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取「Modules」。系統會顯示所有已安裝的 Drupal 模組清單。
- 啟用 SmartDocs 模組。
- 儲存設定。
-
在 Drupal 管理員選單中選取「Modules」。
-
選取「SmartDocs -> 權限」,然後確認「書管理員」角色的「Running the SmartDocs 模組的管理工作」已啟用。
- 在 Drupal 管理選單中,依序選取「Configuration」>「Dev Portal」。
- 將「Connection Timeout」和「Request Timeout」設為 16 秒。
- 儲存設定。
- 進行網址設定:
- 從 Drupal 選單中依序選取「Configuration」>「Search and metadata」>「網址別名」>「設定」。
- 將「別名長度上限」和「元件長度上限」設為 255。
- 展開「Punctuation」。
- 在「左大括號 ({)」和「右大括號 (}」) 設定中,選取「無動作 (不取代)」。
- 按一下「儲存設定」。
- 如果您的開發人員入口網站將提供給內部網路的使用者,且無法存取網際網路,或是部分 API 位於私人網路,請按照下列方式設定 SmartDocs API Proxy 網址:
- 在 Drupal Administration 選單中選取「Configuration」>「SmartDocs」。
- 展開 [進階設定]。
- 按照下列方式更新 SmartDocs Proxy 網址欄位:
<host>/smartdocs/v1/sendrequest
。
內嵌說明應會提供環境的必要值。例如:
https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest
這個欄位預設為https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest
- 按一下「儲存設定」。
建立模式
模型包含 API 表示法的所有資訊。您可以在入口網站上定義多個模型來支援不同的 API,或是將所有 API 組合為單一模型。
每個模型都會指定不重複的內部名稱,該名稱也會定義所產生 Drupal 節點的基準網址。每個 Drupal 節點網址的格式如下:
http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>
其中:
- drupalBasePath:入口網站的基準網址。
- internalName:模型的內部名稱。
- httpMethod:API 的 HTTP 方法,例如:get、put、post 或刪除。
- resourcePath:資源路徑。
舉例來說,如果您將內部名稱指定為「mymodel」,那麼對名為「/books」資源的 GET 要求所產生 Drupal 節點網址時,會如下所示:
http://prod-myco.devportal.apigee.com/mymodel/apis/get/books
如何建立模型
模型建立完成後,系統會將模型儲存在 Edge 機構中,做為 API 結構的來源。詳情請參閱「關於 SmartDoc 模型和範本」。
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取「Content」>「SmartDocs」。
- 選取頁面頂端的「新增模型」。
- 輸入下列欄位:
- 名稱:顯示在網站各處的模型名稱。
- 內部名稱:當您輸入「Name」時,系統會顯示內部名稱。模型的內部名稱,不得與所有模型重複。內部名稱只能使用小寫英文字母、數字和連字號,而且不含空格。選取「編輯」即可編輯這個名稱。
- 說明:模型的說明。
- 選取「建立模型」。
建立模型後,系統會將您重新導向至模型頁面。接下來,您可以使用作業下拉式選單的 bx 執行以下操作:
- 匯入說明 API 的 WADL 檔案,或指定說明 API 的 OpenAPI 規範網址。
- 為模型新增修訂版本
- 修改模型「設定」,包括模型使用的樣式表。
- 將模型匯出至檔案。
- 刪除模型。
將 API 新增至模型
您可以透過以下方式將 API 新增至模型:
- 匯入包含 API 定義的 WADL 檔案
- 匯入 OpenAPI 規格 (OpenAPI 2.0 或 1.2)
- 手動建立資源和方法
您也可以將 SmartDocs JSON 檔案匯入模型。這個檔案一般是先匯出現有模型,編輯檔案,再匯入更新。詳情請參閱下方「匯出及匯入模型」一節。
影片:請觀看短片,瞭解如何匯入 OpenAPI 規範,將 API 新增至 SmartDocs 模型。
匯入 WADL
成功建立模型後,請匯入描述 API 的 WADL 檔案。每次匯入 WADL 檔案時,您都會自動建立新的模型修訂版本。
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取「Content」>「SmartDocs」。
- 選取要更新的模型。
- 選取「作業」下方的「匯入」。
- 在 SmartDocs 匯入頁面的「Choose Format」下拉式選單中,選取「WADL」。
- 在「上傳類型」下拉式選單中選取「檔案」或「網址」。
- 如果您選取「File」,請瀏覽至 WADL 檔案。
- 如果您選取「網址」,請指定 WADL 檔案的網址。
- 按一下「Import」即可匯入至模型。您現在可以轉譯模型。
- 系統會將您重新導向至模型的資訊頁面,讓您現在可以轉譯模型。
匯入 OpenAPI 規範
成功建立模型後,即可匯入 OpenAPI (原稱 Swagger) 規格。Edge 支援 OpenAPI 1.2 和 2.0 版。
OpenAPI 使用包含 JSON 物件的檔案描述 API。每次匯入 OpenAPI 規格時,您都會自動建立新的模型修訂版本。
如何匯入 OpenAPI 規格:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取「Content」(內容) >「SmartDocs」。
- 選取要更新的模型。
- 選取「作業」下方的「匯入」。
- 在 SmartDocs 匯入頁面的「Choose Format」下拉式選單中,選取「Swagger JSON」或「Swagger YAML」。
- 在「Upload Type」(上傳類型) 下拉式選單中選取「File」(檔案) 或「URL」(網址) (您必須針對 OpenAPI 1.2 選取「URL」)。
- 如果您選擇「File」,請瀏覽至 OpenAPI 規格。
- 如果選取「URL」,請指定 OpenAPI 規範的網址。
- 按一下「Import」即可匯入至模型。
- 系統會將您重新導向至模型的資訊頁面,讓您現在可以轉譯模型。
手動建立資源和方法
如果您沒有代表 API 的 WADL 檔案或 OpenAPI 規範,您可以手動將 API 新增至模型。此外,如果您使用 WADL 檔案或 OpenAPI 規範建立模型,可以在匯入後透過這個程序編輯 API,包括新增 API。
如何手動新增 API:
- 建立新的模型修訂版本。
建立修訂版本時,您可以指定模型中所有 API 的單一基本路徑,這表示模型中的所有 API 都共用相同的基本路徑。例如,將基本路徑指定為:
https://myCompany.com/v1
將資源新增至模型時,系統會擴充基礎路徑。 - 為模型定義一或多項資源。資源路徑會與模型修訂版本的基本路徑結合,以指定資源的完整網址。舉例來說,如果您的資源定義了「/login」的路徑,則資源的完整網址如下:
https://myCompany.com/v1/login - 為每個資源定義一或多個方法。方法會指定可對資源叫用的 HTTP 動詞。以「/login」資源為例,您支援登入 POST,以及使用 DELETE 登出。這項資源不支援其他 HTTP 動詞,例如 PUT 或 GET。因此,請為資源定義兩個方法,一個用於 POST,另一個用於 DELETE。
這個方法會使用父項資源的資源網址。因此,所有具有相同網址的方法,都會在 SmartDocs 的單一資源中定義。
原則上:
- 為 API 中的每個不重複基本路徑建立不同的 SmartDocs 模型。
- 為 API 中的各項專屬資源定義不同的 SmartDocs 資源。
- 為資源支援的每種 HTTP 動詞定義不同的 SmartDocs 方法。
建立新的模型修訂版本
您只能將資源新增至模型的現有修訂版本。如果模型已有修訂版本,您可以新增資源。如果是新模型且沒有修訂版本,請建立新的修訂版本。
如要為模型建立新的修訂版本:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取 內容 >SmartDocs。
- 針對您要更新的模型,選取「作業」下方的「新增修訂版本」。
- 在「新增 API 修訂版本」頁面中,輸入下列資訊:
- 顯示名稱:入口網站中顯示的修訂版本名稱。
- 版本 ID:修訂版本的簡短 ID。
- 說明:修訂版本的說明。
- 基準網址:模型修訂版本中所有 API 的基準網址。模型可針對每個修訂版本使用不同的基礎網址。例如,您可以在基準網址中加入版本指標。第一個模型修訂版本的基準網址為:
https://myCompany.com/v1
下一個修訂版本的基準網址可以是:
https://myCompany.com/v2
- 選取「新增修訂版本」。系統會將您重新導向至模型的修訂版本頁面。您現在可以定義模型上的資源。
定義資源
資源會指定 API 的完整網址。定義資源時,您可以指定資源路徑,這個路徑會與模型修訂版本中的基準網址結合,以建立資源的完整網址。
如何定義資源:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取 SmartDocs。
- 針對您要更新的模型,選取「作業」下方的「API 修訂版本」,即可查看模型的所有修訂版本。
- 選取要編輯的修訂版本。
- 在修訂版本頁面的下拉式選單中,選取「新增資源」。
- 在「Add Resource」頁面中輸入下列資訊:
- 顯示名稱:資源的名稱。
- 路徑:資源路徑,開頭為「/」。Path 的值會與模型修訂版本的基準網址結合,以建立資源的完整網址。
- 說明:資源的說明,
- 參數:視需要輸入 JSON 物件,定義資源中的每個參數。這些參數的說明如下。
- 選取「新增資源」。系統會將您重新導向至模型頁面。您現在可以定義資源中的方法。
您可以視需要在資源中加入參數,例如範本、查詢和標頭參數。所有資源參數都會繼承在該資源中定義的任何方法。因此,如果您在資源中定義查詢參數,新增至該資源的所有方法都必須支援該查詢參數。
或者,您也可以在方法上定義參數。舉例來說,POST 方法可能支援 DELETE 方法不支援的查詢參數。因此,請在定義方法時,為方法新增特定參數,如下所示。
下圖顯示 Apigee Approval 或 Revoke Developer App API 的現有 SmartDocs 頁面,醒目顯示各類型的參數:
每個參數類型是由 JSON 物件定義:
類型 |
JSON 物件 |
附註 |
---|---|---|
範本 |
{ |
範本參數一律為必要參數,因此請將 required 設為 true,然後將值省略為 defaultValue。 當使用者將滑鼠遊標懸停在 SmartDocs 頁面中的網址上時,description 值會顯示於彈出式視窗中。 |
查詢 |
{ |
必要的查詢參數仍可指定 defaultValue,但通常不會。 如果是選用的查詢參數,請將 required 設為 false,並指定 defaultValue。 |
標題 |
{ |
請留意如何在說明中使用 HTML 標記。 |
範本參數會在資源路徑中定義變數。例如,您可以在資源上定義兩個範本參數。請注意參數陣列中的各個參數定義如何以半形逗號分隔:
[ { "dataType": "string", "defaultValue": "", "description": "Mention the organization name.", "name": "org_name", "required": true, "type": "TEMPLATE" }, { "dataType": "string", "defaultValue": "", "description": "Mention the user email.", "name": "developer_email", "required": true, "type": "TEMPLATE" } ]
接著,您可以在資源路徑定義中使用範本參數,並以「{}」括住。舉例來說,您可以將路徑設為:
/login/{org_name}/{developer_email}
在 SmartDocs API 頁面中,使用者必須先編輯網址以指定網址的 org_name 和 developer_email 部分,才能提交要求。
定義方法
為每個資源定義一或多個方法。方法定義會指定可對資源叫用的 HTTP 動詞。一項資源可以定義單一方法,或多種方法。
在定義方法時,指定該方法使用的任何參數,包括查詢和標頭參數。如要瞭解如何在方法中新增參數,請參閱上方的資源說明。
下圖顯示 Apigee Create Developer API 的現有 SmartDocs 頁面,頁面中的各個區域以特別框標出您定義方法時所設定的對應值:
下一張圖片顯示相同的頁面,但已選取「要求主體」的說明:
如何定義方法:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取 內容 >SmartDocs。
- 針對您要更新的模型,選取「作業」下方的「API 修訂版本」,即可查看模型的所有修訂版本。
- 選取要編輯的修訂版本。
- 在修訂版本頁面上,從其中一項資源的下拉式選單中選取「Add Method」。
- 在「編輯方法」頁面中輸入下列資訊:
- 顯示名稱:API 的名稱,也會成為 API 的 Drupal 頁面標題。
- 說明:說明 API。
- 方法 Verb:HTTP 動詞類型。
- 安全性配置:為方法指定驗證模式 (如有)。詳情請參閱「設定 SmartDocs 驗證類型」。
- 內容類型:要求和回應的內容類型。請參閱以下章節,瞭解如何設定不同的驗證方法。
- 參數:(選用) 該方法的任何查詢或標頭參數。 詳情請參閱上述說明,瞭解如何將參數新增至資源。
- 要求主體說明文件:(選填) 描述要求主體。POST 和 PUT 方法會接收要求主體。您可以用這個區域描述。如果省略這個值,產生的 SmartDocs 頁面會省略「Request Body」下方的「Description」連結。
- 要求主體範例:(選填) 顯示要求主體的範例,通常以 JSON 物件或 XML 格式呈現。針對 POST 和 PUT 動詞,要求主體範例會在每個要求中傳遞。SmartDocs 頁面的使用者先編輯了這個範例,再向 API 提交要求。如果省略這個值,系統產生的 SmartDocs 頁面中會忽略「Request Body」下方的「Value」連結。
- 標記:與 API 相關聯的標記陣列。SmartDocs 會使用標記將類似的 API 分組。舉例來說,您可以將「統計資料」標記套用至所有與統計資料相關的 API。您可以將不同資源的 API 歸類到單一標記底下。如果這些 API 全都使用相同的標記,
- 選取「新增方法」。系統會將您重新導向至模型頁面。您現在可以轉譯並發布方法。
算繪模型
將 API 新增至模型後,您就能轉譯模型。轉譯作業會將模型的 API 說明轉換為 Drupal 節點。算繪完成後,每個 API 都會有一個 Drupal 節點,其中每個 Drupal 節點都對應至一個 HTML 網頁。
您可以選擇一次轉譯整個模型,也可以選取個別 API 進行算繪。
如何轉譯模型:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取 [內容]>SmartDocs。
- 針對您要轉譯的模型,選取「作業」下方的「API 修訂版本」。
- 選取要轉譯的修訂版本。您只能算繪模型單一修訂版本的節點。
- 選取算繪方法。
- 從「Update」下拉式選單中,選取「Render Nodes」。
- 按一下「更新」。
- 畫面上會顯示載入畫面,查看節點轉譯進度。
節點轉譯完成後,每個 API 的 Drupal 節點 ID 會顯示在模型的「Node Association」(節點關聯) 欄下方。按一下「節點關聯」欄中的連結,即可查看轉譯的節點。
與其選取「轉譯節點」,不如選取「轉譯及發布節點」,即可進行轉譯並立即以 Drupal 節點的形式發布 API。
發布節點
節點發布之前,入口網站使用者不會看到節點。您也可以選擇在轉譯過程中發布節點。如果您選擇不發布節點,則必須在轉譯完成後手動發布節點。
如何發布節點:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取 內容 >SmartDocs。
- 針對您要發布的模型,選取作業下方的「API 修訂版本」。
- 選取要發布的修訂版本。您只能發布模型單一修訂版本的節點。
- 選取發布方法。
- 選取要發布的修訂版本中的節點。
- 從「更新選項」下拉式選單中,選取「發布節點」。
- 按一下「更新」。
- 在「節點關聯」欄下方選取節點 ID,前往節點。
根據預設,已發布 API 節點的 Drupal 網址的格式為:http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>。 如要控制網址形式,請按照下列步驟操作:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中,依序選取「Configuration」>「Search and metadata」>「URLAlias」>「Patterns」。
- 在「所有 SmartDocs Method 路徑」下方指定產生路徑的方式。
- 選取「儲存設定」。
由於在入口網站上進行快取,模型網頁發布後可能不會立即顯示,如有需要,您可以按照下列程序手動清除 SmartDocs HTML 快取:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取「Configuration」>「SmartDocs」。
- 按一下「重新建立 SmartDocs 模型快取」。
取消發布節點
您可以隨時取消發布已發布的節點。取消發布節點後,入口網站使用者就無法查看該節點。
如何取消發布節點:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取 內容 >SmartDocs。
- 針對您要取消發布的模型,選取作業下方的「API 修訂版本」。
- 選取您要取消發布的節點的模型修訂版本。
- 選取要取消發布修訂版本的節點。
- 從「Update」選項下拉式選單中選取「Unpublish」節點。
- 按一下「更新」。
查看模型的修訂版本
如要建立新的模型修訂版本,請將新的 WADL 檔案或 OpenAPI 規格匯入現有模型,或是手動建立新的修訂版本。建立新的修訂版本後,您可以轉譯並發布修訂版本,取代目前發布的 Drupal 節點。
您可以同時轉譯及發布多個修訂版本的節點。換句話說,如果模型有五個修訂版本,您可以從任何或所有修訂版本發布節點。不過,如果在某個模型中發布 API,且該模型與其他模型已發布的節點相同,則系統會取消發布舊版 API,並以最近發布的 API 取代舊版 API。
如要查看模型的修訂版本:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取 內容 >「SmartDocs」。
- 針對您要更新的模型,選取作業下方的「API 修訂版本」。
- 選取要查看的模型修訂版本。
- 按照上述方式轉譯和發布節點。
編輯節點
轉譯節點後,您可以使用 Drupal 編輯器編輯節點。舉例來說,您可以編輯 API 的 HTTP 動詞和說明,或是在 API 中新增查詢或標頭參數。您可以編輯透過 WADL 檔案或 OpenAPI 規格建立的節點,或是手動建立的節點。
您也可以編輯原始 WADL 檔案或 OpenAPI 規格。編輯完成後,請將 WADL 檔案或 OpenAPI 規範匯入模型做為新的修訂版本,然後依照上述方式轉譯並發布變更。
如何使用 Drupal 編輯器編輯節點:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 找到與要編輯的 API 說明文件相對應的 Drupal 節點。
- 選取「Edit」,即可使用 Drupal 編輯器。
- 編輯完成後,請選取「更新方法」。
您也可以透過 SmartDocs 模型編輯節點:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取內容 >「SmartDocs」。
- 針對您要更新的模型,選取作業下方的「API 修訂版本」。
- 選取要發布的模型修訂版本。
- 針對要編輯的方法,在「Operations」(作業) 下拉式選單中選取「Edit method」(編輯方法)。
如要刪除節點:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取內容 >「SmartDocs」。
- 針對您要更新的模型,選取作業下方的「API 修訂版本」。
- 選取要發布的模型修訂版本。
- 在「作業」下拉式選單中,選取該方法的「刪除方法」。
注意:刪除節點也會將該 API 從模型中移除。如果只想取消發布 API,不讓入口網站使用者看到這個 API,但不想將其從模型中刪除,請按照上述方式取消發布節點。
入口網站內建的報表會顯示 SmartDocs 模型轉譯的任何節點相關資訊,但該模型不再參照模型的有效方法。如要存取報表,請在 Drupal 選單中選取「報表」,然後選取名為「SmartDocs 節點狀態」的報表。
匯出及匯入模型
SmartDocs 可讓您將現有模型匯出至檔案。例如,您可以定義實際工作環境和暫存環境。接下來,您就能在測試環境中進行所有 SmartDocs 編輯作業。當您準備好發布 API 時,請匯出暫存模型並匯入至實際工作環境模型。
匯入模型會建立一個新的模型修訂版本。SmartDocs 會嘗試將模型中的現有 API 與匯入的 API 進行比對。如果 SmartDocs 偵測到相符項目,匯入作業會更新與現有 API 對應的 Drupal 節點。如果 SmartDocs 未偵測到相符項目,則匯入作業會為 API 建立新的 Drupal 節點。
例如,您有一個 POST API,其對應 ID 為 91 的 Drupal 節點。接著,您匯入模型,SmartDocs 偵測到匯入模型中的 POST API 與現有 POST API 相符。更新 POST API 之後,即可更新 Drupal 節點 91。如果 SmartDocs 未偵測到相符項目,則會以新的 ID 建立新的 Drupal 節點。
Drupal 利用下列 API 特性執行相符項目:
- internalName:內部模型名稱。
- httpMethod:API 的 HTTP 方法,例如 GET、PUT、POST 或 DELETE。
- resourcePath:資源路徑。
- 查詢參數:API 使用的任何查詢參數。
如果匯入的 API 全都符合模型中現有的 API,則 SmartDocs 會更新現有的 Drupal 節點。
匯出的模型會以單一 JSON 物件表示,內含資源和方法項目。也就是說,您可以編輯匯出的模型來修改資源或方法,然後重新匯入模型。如果您編輯 JSON 物件,請勿修改下列欄位:
- revisionNumber
- createdTime
- modifiedTime
- apiRevisionId
- resourceId
如何匯出模型:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取 內容 >「SmartDocs」。
- 針對您要匯出的模型,選取「作業」下方的「匯出」。
- 將匯出檔案類型設為 SmartDocs JSON。
- 按一下「匯出」。
- 系統會提示您將檔案儲存到磁碟,或是在編輯器中開啟檔案。
如何匯入模型:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取 內容 >「SmartDocs」。
- 針對您要匯入的模型,選取「作業」下方的「匯入」。
- 在「選擇格式」下拉式選單中,選取「SmartDocs JSON」。
-
在 上傳類型中選取「檔案」 或「網址」:
- 如果您選取「File」,請瀏覽至 JSON 檔案。
- 如果選取「網址」,請指定 SmartDocs JSON 檔案的網址。
- 按一下「Import」即可匯入至模型。
- 系統會將您重新導向至模型的資訊頁面,讓您現在可以轉譯模型。請注意,匯入作業會建立新的模型修訂版本。
- 轉譯並發布節點。
編輯 SmartDocs 範本
SmartDocs 範本可定義 Drupal 節點在畫面上的顯示方式。每個 SmartDocs 模型都可使用相同的預設範本,您也可以手動自訂用於個別模型的範本。
SmartDocs 範本有一個範本檔案,編碼為 .hbr 檔案、CSS 檔案和 JavaScript 檔案。使用 Handlebar 時,大部分的內容都是透過內嵌控制列運算式 (例如 &123;&123;body}}
) 驅動。現有 Handlebar 運算式的清單會顯示在檔案頂端的註解中。如要進一步瞭解如何使用 Handlebar 自訂範本,請前往 http://handlebarsjs.com。
以下各節說明如何上傳自訂 SmartDocs 範本檔案,供所有新模型或將新的 API 匯入現有模型時使用、如何還原原始預設的 SmartDocs 範本檔案,以及如何修改個別模型的 SmartDocs 範本。
上傳自訂 SmartDocs 範本檔案
您可以上傳自訂的 SmartDocs 範本檔案,作為 Handlebar .hbr 檔案,在建立新模型或將新 API 匯入現有模型時做為預設範本。
如要在建立自訂 SmartDocs 範本檔案時,以預設的 SmartDocs 範本檔案為基礎,下載以下項目:profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr
如何上傳自訂的 SmartDocs 範本檔案:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取「Configuration」>「SmartDocs」。
- 展開頁面中的「進階設定」區域。
- 在「上傳自訂方法範本」下方,按一下「選擇檔案」,然後前往「處理列」.hbr 檔案。
- 按一下「上傳」。
- 按一下「儲存設定」。
還原預設的 SmartDocs 範本檔案
您可以還原預設的 SmartDocs 範本檔案。還原之後,系統就會在建立新模型,或將新的 API 匯入現有模型時,使用預設的 SmartDocs 範本檔案。
如何還原預設的 SmartDocs 範本檔案:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取「Configuration」>「SmartDocs」。
- 展開頁面中的「進階設定」區域。
- 在「上傳自訂方法」範本下方,按一下自訂 SmartDocs 範本檔案旁的「移除」。
- 按一下「儲存設定」。
修改個別模型的 SmartDocs 範本
您可以修改個別模型使用的範本。
如何修改獨立模型的範本:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 選擇 內容 > Drupal 管理選單中的「SmartDocs」。
- 找出要編輯的模型,選取「作業」底下的「設定」。
- 在「方法範本」區域中,視需要編輯範本。
- 按一下 [儲存範本]。
- 瀏覽至 Drupal 節點。頁面應該會顯示您的範本異動。
設定 SmartDocs 驗證類型
SmartDocs 中定義的 API 可為開啟,意味著不需驗證憑證即可存取這些 API,或者安全地存取 API。安全的 API 會要求您在呼叫 API 時通過憑證。
針對安全的 API,SmartDocs 支援下列驗證類型:
- 基本驗證 - 做為使用者名稱和密碼組合傳遞基本驗證憑證。如未指定使用 OAuth 做為憑證類型,API 會預設為使用基本驗證。
- OAuth 2.0:第三方服務供應商會驗證使用者的憑證,確保使用者擁有 API 授權,然後核發存取權杖。向受保護的 API 提出 SmartDocs 要求時,SmartDocs 會建立要求並傳送給服務供應商。接著,服務供應商會驗證權杖,並確保權杖尚未過期。
- 自訂權杖 - 將權杖值做為標頭或查詢參數傳送至每個要求。
您可以針對每種驗證類型建立「安全性配置」,定義驗證的特性。舉例來說,如果是自訂權杖驗證,安全性配置會定義權杖傳遞方式 (標頭、查詢參數、內文參數) 和權杖名稱。
安全性配置與模型的特定修訂版本相關聯。因此,如果您建立了模型的新修訂版本,就必須重新定義該修訂版本的安全性配置。
在 WADL 檔案中,您可以使用 <apigee:authentication> Apigee 標記,指定 API 是否需要進行驗證,如下所示:
<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline"> ... <apigee:authentication required="true"/> </method>
若 API 已開啟,請將 required 屬性設為 false。
請注意,您無法在 WADL 檔案中指定驗證類型。方法是編輯 Drupal 中的節點。如要進一步瞭解 WADL 檔案,請參閱 WADL 參考資料。
在 Drupal 的 API 頁面中,SmartDocs 新增下列按鈕,讓使用者指定基本驗證憑證:
如果您編輯節點將驗證類型設為 OAuth,則 SmartDocs 會在頁面中加入下列按鈕:
針對自訂權杖,SmartDocs 新增了下列項目:
設定基本驗證
如果您透過 API 使用基本驗證,則只需要在用來建立模型的 WADL 檔案中指定 <apigee:authentication> 標記。
如要將基本驗證方法套用至透過 WADL 檔案以外的來源建立的方法:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取內容 >「SmartDocs」。
- 針對所需模型,選取「作業」下方的「API 修訂版本」。
- 針對您要編輯的模型修訂版本,選取「Operations」(作業) 底下的「Security Settings」(安全性設定)。
- 選取「新增安全性配置」。
- 指定安全性配置的名稱。
- 在「Type」(類型) 部分選取「Basic」。
- 選取 [提交]。
- 針對模型中的每個方法,編輯該方法,將其「安全性配置」設為基本配置。
- 在 Drupal 管理選單中選取內容 >「SmartDocs」。
- 針對所需模型,選取「作業」下方的「API 修訂版本」。
- 針對您要編輯的模型修訂版本,選取「Operations」(作業) 下方的「Revision Details」(修訂版本詳細資料)。
- 針對要編輯的 API,選取「Edit Method」(編輯方法)。
- 選取 API 的「Security Scheme」。
- 儲存 API。
設定 OAuth 2.0 驗證
您可以將模型設定為在 SmartDocs 中使用 OAuth 2.0,而非使用基本驗證的預設選項。您可在兩個位置設定 OAuth:
- 在「安全性設定」下方,為模型的每個修訂版本建立安全性配置。
- 在「Settings」(設定) 底下,為模型的所有修訂版本指定用戶端 ID 和用戶端密鑰。
如何啟用 OAuth:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取內容 >「SmartDocs」。
- 選取所需模型,在「作業」下方選取「API 修訂版本」。
- 針對您要編輯的模型修訂版本,選取「作業」底下的「安全性設定」。
- 選取「新增安全性配置」。
- 指定安全性配置的名稱。
- 選取「OAuth 2.0」做為「Type」。
- 設定「授權類型」。
- 在「授權網址」欄位中輸入值。「授權網址」可用於取得存取權杖。
- 將「授權動詞」設為 GET 或 POST。
- 輸入「Access Token URL」(存取權杖網址)。「存取權杖網址」是用來將要求權杖交換要求權杖的網址。
- 輸入「存取權杖參數名稱」。
- 使用 In 指定如何傳送符記:Header、Query 或 Body。
- 設定 OAuth 範圍。
- 選取 [提交]。
- 在 Drupal 管理選單中選取內容 >「SmartDocs」。
- 針對模型,選取「Operations」(作業) 下拉式選單中的「Settings」(設定)。
- 在「用戶端 ID」和「用戶端密鑰」中輸入值。
- 選取「儲存範本驗證設定」。
- 編輯模型中每種方法的「安全性配置」,將其「安全性配置」設為 OAuth 安全性配置。
- 在 Drupal 管理選單中選取內容 >「SmartDocs」。
- 針對所需模型,選取「作業」下方的「API 修訂版本」。
- 針對您要編輯的模型修訂版本,選取「Operations」(作業) 下方的「Revision Details」(修訂版本詳細資料)。
- 針對要編輯的 API,選取「Edit Method」(編輯方法)。
- 選取 API 的「Security Scheme」。
- 儲存 API。
設定自訂權杖驗證
您可以設定模型來使用自訂權杖驗證。
如何啟用自訂權杖:
- 以具備管理員或內容建立權限的使用者登入入口網站。
- 在 Drupal 管理選單中選取內容 >「SmartDocs」。
- 針對所需模型,選取「作業」下方的「API 修訂版本」。
- 針對您要編輯的模型修訂版本,選取「Operations」(作業) 底下的「Security Settings」(安全性設定)。
- 選取「新增安全性配置」。
- 指定安全性配置的名稱。
- 在「Type」(類型) 中選取「Apikey」。
- 設定包含符記的「Param」名稱。
- 使用 In 指定如何傳送符記:Header、Query 或 Body。
- 選取 [提交]。
- 編輯模型中每個方法的安全性配置至權杖配置。
- 在 Drupal 管理選單中選取內容 >「SmartDocs」。
- 針對所需模型,選取「作業」下方的「API 修訂版本」。
- 針對您要編輯的模型修訂版本,選取「Operations」(作業) 下方的「Revision Details」(修訂版本詳細資料)。
- 針對要編輯的 API,選取「Edit Method」(編輯方法)。
- 選取 API 的「Security Scheme」。
- 儲存 API。
刪除模型
當您刪除模型 (依序點選 Content > SmartDocs,以及 Drupal 中「Operation」欄位中的「Delete」) 後,該模型就會從 Edge 機構中刪除。也就是說,如果其他入口網站正在參照該模型,就無法再使用該模型。詳情請參閱「關於 SmartDoc 模型和範本」。