使用 SmartDoc 記錄 API

您正在查看 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:

  1. 按一下「Hello World API」。系統會顯示 Hello World API 摘要頁面:
  2. 按一下「View API affirmation」,系統會顯示這項資源的 SmartDocs:
  3. 按一下「傳送這項要求」
  4. 查看傳回的回應:
    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>
    
  5. 按一下「要求」分頁標籤查看要求,或按一下「cURL」分頁標籤查看對應的 cURL 呼叫。

如何使用 SmartDocs 記錄 API

SmartDocs 會使用「模型」model呈現您的 API,模型中包含您 API 的所有相關資訊。入口網站會從模型擷取您的 API 相關資訊,以將入口網站上的說明文件頁面顯示為 Drupal 節點,其中每個 Drupal 節點會對應入口網站的說明文件頁面。

以下為使用 SmartDocs 的一般步驟:

  1. 在入口網站上設定 Drupal SmartDocs 模組。
  2. 建立 SmartDocs 模型。
  3. 透過 WADL 檔案、OpenAPI (舊稱 Swagger) 規格或手動新增 API 至模型。
  4. 以 Drupal 節點集合的形式轉譯模型。每個 Drupal 節點都包含單一 API 的相關資訊。舉例來說,如果 API 中的資源同時支援 POST 和 PUT 要求,SmartDocs 會為 POST 和 PUT 分別建立 Drupal 節點。
  5. 發布 Drupal 節點。發布後,入口網站使用者就能查看 API 並進行互動。
  6. 在發布 Drupal 節點前後編輯。您可以使用 Drupal 編輯器,或編輯原始 WADL 檔案或 OpenAPI 規格來編輯 Drupal 節點。編輯 WADL 檔案或 OpenAPI 規範後,請將其匯入模型做為新的修訂版本,然後轉譯並發布變更。
  7. 啟用 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 模組:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取「Modules」。系統會顯示所有已安裝的 Drupal 模組清單。
  3. 啟用 SmartDocs 模組。
  4. 儲存設定。
  5. 在 Drupal 管理員選單中選取「Modules」
  6. 選取「SmartDocs -> 權限」,然後確認「書管理員」角色的「Running the SmartDocs 模組的管理工作」已啟用。
  7. 在 Drupal 管理選單中,依序選取「Configuration」>「Dev Portal」
  8. 將「Connection Timeout」和「Request Timeout」設為 16 秒。
  9. 儲存設定。
  10. 進行網址設定:
    1. 從 Drupal 選單中依序選取「Configuration」>「Search and metadata」>「網址別名」>「設定」
    2. 將「別名長度上限」和「元件長度上限」設為 255
    3. 展開「Punctuation」
    4. 在「左大括號 ({)」和「右大括號 (}」) 設定中,選取「無動作 (不取代)」
    5. 按一下「儲存設定」
  11. 如果您的開發人員入口網站將提供給內部網路的使用者,且無法存取網際網路,或是部分 API 位於私人網路,請按照下列方式設定 SmartDocs API Proxy 網址:
    1. 在 Drupal Administration 選單中選取「Configuration」>「SmartDocs」
    2. 展開 [進階設定]
    3. 按照下列方式更新 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
    4. 按一下「儲存設定」

建立模式

模型包含 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 模型和範本」。

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取「Content」>「SmartDocs」。
  3. 選取頁面頂端的「新增模型」
  4. 輸入下列欄位:
    • 名稱:顯示在網站各處的模型名稱。
    • 內部名稱:當您輸入「Name」時,系統會顯示內部名稱。模型的內部名稱,不得與所有模型重複。內部名稱只能使用小寫英文字母、數字和連字號,而且不含空格。選取「編輯」即可編輯這個名稱。
    • 說明:模型的說明。
  5. 選取「建立模型」

建立模型後,系統會將您重新導向至模型頁面。接下來,您可以使用作業下拉式選單的 bx 執行以下操作:

  • 匯入說明 API 的 WADL 檔案,或指定說明 API 的 OpenAPI 規範網址。
  • 為模型新增修訂版本
  • 修改模型「設定」,包括模型使用的樣式表。
  • 將模型匯出至檔案。
  • 刪除模型。

將 API 新增至模型

您可以透過以下方式將 API 新增至模型:

  • 匯入包含 API 定義的 WADL 檔案
  • 匯入 OpenAPI 規格 (OpenAPI 2.0 或 1.2)
  • 手動建立資源和方法

您也可以將 SmartDocs JSON 檔案匯入模型。這個檔案一般是先匯出現有模型,編輯檔案,再匯入更新。詳情請參閱下方「匯出及匯入模型」一節。

影片:請觀看短片,瞭解如何匯入 OpenAPI 規範,將 API 新增至 SmartDocs 模型。

匯入 WADL

成功建立模型後,請匯入描述 API 的 WADL 檔案。每次匯入 WADL 檔案時,您都會自動建立新的模型修訂版本。

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取「Content」>「SmartDocs」。
  3. 選取要更新的模型。
  4. 選取「作業」下方的「匯入」
  5. 在 SmartDocs 匯入頁面的「Choose Format」下拉式選單中,選取「WADL」
  6. 在「上傳類型」下拉式選單中選取「檔案」或「網址」
    1. 如果您選取「File」,請瀏覽至 WADL 檔案。
    2. 如果您選取「網址」,請指定 WADL 檔案的網址。
  7. 按一下「Import」即可匯入至模型。您現在可以轉譯模型。
  8. 系統會將您重新導向至模型的資訊頁面,讓您現在可以轉譯模型。

匯入 OpenAPI 規範

成功建立模型後,即可匯入 OpenAPI (原稱 Swagger) 規格。Edge 支援 OpenAPI 1.2 和 2.0 版。

OpenAPI 使用包含 JSON 物件的檔案描述 API。每次匯入 OpenAPI 規格時,您都會自動建立新的模型修訂版本。

如何匯入 OpenAPI 規格:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取「Content」(內容) >「SmartDocs」
  3. 選取要更新的模型。
  4. 選取「作業」下方的「匯入」
  5. 在 SmartDocs 匯入頁面的「Choose Format」下拉式選單中,選取「Swagger JSON」或「Swagger YAML」
  6. 在「Upload Type」(上傳類型) 下拉式選單中選取「File」(檔案) 或「URL」(網址) (您必須針對 OpenAPI 1.2 選取「URL」)。
    1. 如果您選擇「File」,請瀏覽至 OpenAPI 規格。
    2. 如果選取「URL」,請指定 OpenAPI 規範的網址。
  7. 按一下「Import」即可匯入至模型。
  8. 系統會將您重新導向至模型的資訊頁面,讓您現在可以轉譯模型。

手動建立資源和方法

如果您沒有代表 API 的 WADL 檔案或 OpenAPI 規範,您可以手動將 API 新增至模型。此外,如果您使用 WADL 檔案或 OpenAPI 規範建立模型,可以在匯入後透過這個程序編輯 API,包括新增 API。

如何手動新增 API:

  1. 建立新的模型修訂版本。

    建立修訂版本時,您可以指定模型中所有 API 的單一基本路徑,這表示模型中的所有 API 都共用相同的基本路徑。例如,將基本路徑指定為:

    https://myCompany.com/v1

    將資源新增至模型時,系統會擴充基礎路徑。
  2. 為模型定義一或多項資源。資源路徑會與模型修訂版本的基本路徑結合,以指定資源的完整網址。舉例來說,如果您的資源定義了「/login」的路徑,則資源的完整網址如下:

    https://myCompany.com/v1/login
  3. 為每個資源定義一或多個方法。方法會指定可對資源叫用的 HTTP 動詞。以「/login」資源為例,您支援登入 POST,以及使用 DELETE 登出。這項資源不支援其他 HTTP 動詞,例如 PUT 或 GET。因此,請為資源定義兩個方法,一個用於 POST,另一個用於 DELETE。

    這個方法會使用父項資源的資源網址。因此,所有具有相同網址的方法,都會在 SmartDocs 的單一資源中定義。

原則上:

  • 為 API 中的每個不重複基本路徑建立不同的 SmartDocs 模型。
  • 為 API 中的各項專屬資源定義不同的 SmartDocs 資源。
  • 為資源支援的每種 HTTP 動詞定義不同的 SmartDocs 方法。

建立新的模型修訂版本

您只能將資源新增至模型的現有修訂版本。如果模型已有修訂版本,您可以新增資源。如果是新模型且沒有修訂版本,請建立新的修訂版本。

如要為模型建立新的修訂版本:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取 內容 >SmartDocs。
  3. 針對您要更新的模型,選取「作業」下方的「新增修訂版本」
  4. 在「新增 API 修訂版本」頁面中,輸入下列資訊:
    • 顯示名稱:入口網站中顯示的修訂版本名稱。
    • 版本 ID:修訂版本的簡短 ID。
    • 說明:修訂版本的說明。
    • 基準網址:模型修訂版本中所有 API 的基準網址。模型可針對每個修訂版本使用不同的基礎網址。例如,您可以在基準網址中加入版本指標。第一個模型修訂版本的基準網址為:
      https://myCompany.com/v1
      下一個修訂版本的基準網址可以是:
      https://myCompany.com/v2
  5. 選取「新增修訂版本」。系統會將您重新導向至模型的修訂版本頁面。您現在可以定義模型上的資源。

定義資源

資源會指定 API 的完整網址。定義資源時,您可以指定資源路徑,這個路徑會與模型修訂版本中的基準網址結合,以建立資源的完整網址。

如何定義資源:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取 SmartDocs。
  3. 針對您要更新的模型,選取「作業」下方的「API 修訂版本」,即可查看模型的所有修訂版本。
  4. 選取要編輯的修訂版本。
  5. 在修訂版本頁面的下拉式選單中,選取「新增資源」
  6. 在「Add Resource」頁面中輸入下列資訊:
    • 顯示名稱:資源的名稱。
    • 路徑:資源路徑,開頭為「/」。Path 的值會與模型修訂版本的基準網址結合,以建立資源的完整網址。
    • 說明:資源的說明,
    • 參數:視需要輸入 JSON 物件,定義資源中的每個參數。這些參數的說明如下。
  7. 選取「新增資源」。系統會將您重新導向至模型頁面。您現在可以定義資源中的方法。

您可以視需要在資源中加入參數,例如範本、查詢和標頭參數。所有資源參數都會繼承在該資源中定義的任何方法。因此,如果您在資源中定義查詢參數,新增至該資源的所有方法都必須支援該查詢參數。

或者,您也可以在方法上定義參數。舉例來說,POST 方法可能支援 DELETE 方法不支援的查詢參數。因此,請在定義方法時,為方法新增特定參數,如下所示。

下圖顯示 Apigee Approval 或 Revoke Developer App API 的現有 SmartDocs 頁面,醒目顯示各類型的參數:

每個參數類型是由 JSON 物件定義:

類型

JSON 物件

附註

範本

{
"dataType": "string",
"defaultValue": "",
"description": "機構名稱。",
"name": "org_name",
"required": true,
"type": "TEMPLATE"
}

範本參數一律為必要參數,因此請將 required 設為 true,然後將值省略為 defaultValue

當使用者將滑鼠遊標懸停在 SmartDocs 頁面中的網址上時,description 值會顯示於彈出式視窗中。

查詢

{
"dataType": "string",
"defaultValue": "",
"description": "地點。",
"name": "w",
"required": true,
"type": "QUERY"
}

必要的查詢參數仍可指定 defaultValue,但通常不會。

如果是選用的查詢參數,請將 required 設為 false,並指定 defaultValue

標題

{
"dataType": "string",
"defaultValue": "application/json",
"description": "以 <code>application/json</code> 形式指定。",
"name": "Content-Type",
"required": true,
"type": "HEADER"
}

請留意如何在說明中使用 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_namedeveloper_email 部分,才能提交要求。

定義方法

為每個資源定義一或多個方法。方法定義會指定可對資源叫用的 HTTP 動詞。一項資源可以定義單一方法,或多種方法。

在定義方法時,指定該方法使用的任何參數,包括查詢和標頭參數。如要瞭解如何在方法中新增參數,請參閱上方的資源說明。

下圖顯示 Apigee Create Developer API 的現有 SmartDocs 頁面,頁面中的各個區域以特別框標出您定義方法時所設定的對應值:

下一張圖片顯示相同的頁面,但已選取「要求主體」的說明:

如何定義方法:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取 內容 >SmartDocs。
  3. 針對您要更新的模型,選取「作業」下方的「API 修訂版本」,即可查看模型的所有修訂版本。
  4. 選取要編輯的修訂版本。
  5. 在修訂版本頁面上,從其中一項資源的下拉式選單中選取「Add Method」
  6. 在「編輯方法」頁面中輸入下列資訊:
    • 顯示名稱: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 全都使用相同的標記,
  7. 選取「新增方法」。系統會將您重新導向至模型頁面。您現在可以轉譯並發布方法。

算繪模型

將 API 新增至模型後,您就能轉譯模型。轉譯作業會將模型的 API 說明轉換為 Drupal 節點。算繪完成後,每個 API 都會有一個 Drupal 節點,其中每個 Drupal 節點都對應至一個 HTML 網頁。

您可以選擇一次轉譯整個模型,也可以選取個別 API 進行算繪。

如何轉譯模型:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取 [內容]>SmartDocs。
  3. 針對您要轉譯的模型,選取「作業」下方的「API 修訂版本」
  4. 選取要轉譯的修訂版本。您只能算繪模型單一修訂版本的節點。
  5. 選取算繪方法。
  6. 從「Update」下拉式選單中,選取「Render Nodes」
  7. 按一下「更新」
  8. 畫面上會顯示載入畫面,查看節點轉譯進度。
    節點轉譯完成後,每個 API 的 Drupal 節點 ID 會顯示在模型的「Node Association」(節點關聯) 欄下方。按一下「節點關聯」欄中的連結,即可查看轉譯的節點。

與其選取「轉譯節點」,不如選取「轉譯及發布節點」,即可進行轉譯並立即以 Drupal 節點的形式發布 API。

發布節點

節點發布之前,入口網站使用者不會看到節點。您也可以選擇在轉譯過程中發布節點。如果您選擇不發布節點,則必須在轉譯完成後手動發布節點。

如何發布節點:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取 內容 >SmartDocs。
  3. 針對您要發布的模型,選取作業下方的「API 修訂版本」
  4. 選取要發布的修訂版本。您只能發布模型單一修訂版本的節點。
  5. 選取發布方法。
  6. 選取要發布的修訂版本中的節點。
  7. 從「更新選項」下拉式選單中,選取「發布節點」
  8. 按一下「更新」
  9. 在「節點關聯」欄下方選取節點 ID,前往節點。

根據預設,已發布 API 節點的 Drupal 網址的格式為:http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>。 如要控制網址形式,請按照下列步驟操作:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中,依序選取「Configuration」>「Search and metadata」>「URLAlias」>「Patterns」
  3. 在「所有 SmartDocs Method 路徑」下方指定產生路徑的方式。
  4. 選取「儲存設定」

由於在入口網站上進行快取,模型網頁發布後可能不會立即顯示,如有需要,您可以按照下列程序手動清除 SmartDocs HTML 快取:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取「Configuration」>「SmartDocs」
  3. 按一下「重新建立 SmartDocs 模型快取」

取消發布節點

您可以隨時取消發布已發布的節點。取消發布節點後,入口網站使用者就無法查看該節點。

如何取消發布節點:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取 內容 >SmartDocs。
  3. 針對您要取消發布的模型,選取作業下方的「API 修訂版本」
  4. 選取您要取消發布的節點的模型修訂版本。
  5. 選取要取消發布修訂版本的節點。
  6. 從「Update」選項下拉式選單中選取「Unpublish」節點。
  7. 按一下「更新」

查看模型的修訂版本

如要建立新的模型修訂版本,請將新的 WADL 檔案或 OpenAPI 規格匯入現有模型,或是手動建立新的修訂版本。建立新的修訂版本後,您可以轉譯並發布修訂版本,取代目前發布的 Drupal 節點。

您可以同時轉譯及發布多個修訂版本的節點。換句話說,如果模型有五個修訂版本,您可以從任何或所有修訂版本發布節點。不過,如果在某個模型中發布 API,且該模型與其他模型已發布的節點相同,則系統會取消發布舊版 API,並以最近發布的 API 取代舊版 API。

如要查看模型的修訂版本:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取 內容 >「SmartDocs」。
  3. 針對您要更新的模型,選取作業下方的「API 修訂版本」
  4. 選取要查看的模型修訂版本。
  5. 按照上述方式轉譯和發布節點。

編輯節點

轉譯節點後,您可以使用 Drupal 編輯器編輯節點。舉例來說,您可以編輯 API 的 HTTP 動詞和說明,或是在 API 中新增查詢或標頭參數。您可以編輯透過 WADL 檔案或 OpenAPI 規格建立的節點,或是手動建立的節點。

您也可以編輯原始 WADL 檔案或 OpenAPI 規格。編輯完成後,請將 WADL 檔案或 OpenAPI 規範匯入模型做為新的修訂版本,然後依照上述方式轉譯並發布變更。

如何使用 Drupal 編輯器編輯節點:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 找到與要編輯的 API 說明文件相對應的 Drupal 節點。
  3. 選取「Edit」,即可使用 Drupal 編輯器。
  4. 編輯完成後,請選取「更新方法」

您也可以透過 SmartDocs 模型編輯節點:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取內容 >「SmartDocs」。
  3. 針對您要更新的模型,選取作業下方的「API 修訂版本」
  4. 選取要發布的模型修訂版本。
  5. 針對要編輯的方法,在「Operations」(作業) 下拉式選單中選取「Edit method」(編輯方法)

如要刪除節點:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取內容 >「SmartDocs」。
  3. 針對您要更新的模型,選取作業下方的「API 修訂版本」
  4. 選取要發布的模型修訂版本。
  5. 在「作業」下拉式選單中,選取該方法的「刪除方法」
    注意:刪除節點也會將該 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

如何匯出模型:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取 內容 >「SmartDocs」。
  3. 針對您要匯出的模型,選取「作業」下方的「匯出」
  4. 將匯出檔案類型設為 SmartDocs JSON
  5. 按一下「匯出」
  6. 系統會提示您將檔案儲存到磁碟,或是在編輯器中開啟檔案。

如何匯入模型:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取 內容 >「SmartDocs」。
  3. 針對您要匯入的模型,選取「作業」下方的「匯入」
  4. 在「選擇格式」下拉式選單中,選取「SmartDocs JSON」。
  5. 上傳類型中選取「檔案」 或「網址」
    1. 如果您選取「File」,請瀏覽至 JSON 檔案。
    2. 如果選取「網址」,請指定 SmartDocs JSON 檔案的網址。
  6. 按一下「Import」即可匯入至模型。
  7. 系統會將您重新導向至模型的資訊頁面,讓您現在可以轉譯模型。請注意,匯入作業會建立新的模型修訂版本。
  8. 轉譯並發布節點。

編輯 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 範本檔案:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取「Configuration」>「SmartDocs」
  3. 展開頁面中的「進階設定」區域。
  4. 在「上傳自訂方法範本」下方,按一下「選擇檔案」,然後前往「處理列」.hbr 檔案。
  5. 按一下「上傳」
  6. 按一下「儲存設定」

還原預設的 SmartDocs 範本檔案

您可以還原預設的 SmartDocs 範本檔案。還原之後,系統就會在建立新模型,或將新的 API 匯入現有模型時,使用預設的 SmartDocs 範本檔案。

如何還原預設的 SmartDocs 範本檔案:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取「Configuration」>「SmartDocs」
  3. 展開頁面中的「進階設定」區域。
  4. 在「上傳自訂方法」範本下方,按一下自訂 SmartDocs 範本檔案旁的「移除」
  5. 按一下「儲存設定」

修改個別模型的 SmartDocs 範本

您可以修改個別模型使用的範本。

如何修改獨立模型的範本:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 選擇 內容 > Drupal 管理選單中的「SmartDocs」。
  3. 找出要編輯的模型,選取「作業」底下的「設定」
  4. 在「方法範本」區域中,視需要編輯範本。
  5. 按一下 [儲存範本]。
  6. 瀏覽至 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 檔案以外的來源建立的方法:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取內容 >「SmartDocs」。
  3. 針對所需模型,選取「作業」下方的「API 修訂版本」
  4. 針對您要編輯的模型修訂版本,選取「Operations」(作業) 底下的「Security Settings」(安全性設定)
  5. 選取「新增安全性配置」
  6. 指定安全性配置的名稱
  7. 在「Type」(類型) 部分選取「Basic」
  8. 選取 [提交]。
  9. 針對模型中的每個方法,編輯該方法,將其「安全性配置」設為基本配置。
    1. 在 Drupal 管理選單中選取內容 >「SmartDocs」。
    2. 針對所需模型,選取「作業」下方的「API 修訂版本」
    3. 針對您要編輯的模型修訂版本,選取「Operations」(作業) 下方的「Revision Details」(修訂版本詳細資料)
    4. 針對要編輯的 API,選取「Edit Method」(編輯方法)
    5. 選取 API 的「Security Scheme」
    6. 儲存 API。

設定 OAuth 2.0 驗證

您可以將模型設定為在 SmartDocs 中使用 OAuth 2.0,而非使用基本驗證的預設選項。您可在兩個位置設定 OAuth:

  1. 在「安全性設定」下方,為模型的每個修訂版本建立安全性配置。
  2. 在「Settings」(設定) 底下,為模型的所有修訂版本指定用戶端 ID 和用戶端密鑰。

如何啟用 OAuth:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取內容 >「SmartDocs」。
  3. 選取所需模型,在「作業」下方選取「API 修訂版本」
  4. 針對您要編輯的模型修訂版本,選取「作業」底下的「安全性設定」
  5. 選取「新增安全性配置」
  6. 指定安全性配置的名稱
  7. 選取「OAuth 2.0」做為「Type」
  8. 設定「授權類型」
  9. 在「授權網址」欄位中輸入值。「授權網址」可用於取得存取權杖。
  10. 將「授權動詞」設為 GET 或 POST。
  11. 輸入「Access Token URL」(存取權杖網址)。「存取權杖網址」是用來將要求權杖交換要求權杖的網址。
  12. 輸入「存取權杖參數名稱」
  13. 使用 In 指定如何傳送符記:HeaderQueryBody
  14. 設定 OAuth 範圍
  15. 選取 [提交]。
  16. 在 Drupal 管理選單中選取內容 >「SmartDocs」。
  17. 針對模型,選取「Operations」(作業) 下拉式選單中的「Settings」(設定)
  18. 在「用戶端 ID」和「用戶端密鑰」中輸入值。
  19. 選取「儲存範本驗證設定」
  20. 編輯模型中每種方法的「安全性配置」,將其「安全性配置」設為 OAuth 安全性配置。
    1. 在 Drupal 管理選單中選取內容 >「SmartDocs」。
    2. 針對所需模型,選取「作業」下方的「API 修訂版本」
    3. 針對您要編輯的模型修訂版本,選取「Operations」(作業) 下方的「Revision Details」(修訂版本詳細資料)
    4. 針對要編輯的 API,選取「Edit Method」(編輯方法)
    5. 選取 API 的「Security Scheme」
    6. 儲存 API。

設定自訂權杖驗證

您可以設定模型來使用自訂權杖驗證。

如何啟用自訂權杖:

  1. 以具備管理員或內容建立權限的使用者登入入口網站。
  2. 在 Drupal 管理選單中選取內容 >「SmartDocs」。
  3. 針對所需模型,選取「作業」下方的「API 修訂版本」
  4. 針對您要編輯的模型修訂版本,選取「Operations」(作業) 底下的「Security Settings」(安全性設定)
  5. 選取「新增安全性配置」
  6. 指定安全性配置的名稱
  7. 在「Type」(類型) 中選取「Apikey」。
  8. 設定包含符記的「Param」名稱
  9. 使用 In 指定如何傳送符記:HeaderQueryBody
  10. 選取 [提交]。
  11. 編輯模型中每個方法的安全性配置至權杖配置。
    1. 在 Drupal 管理選單中選取內容 >「SmartDocs」。
    2. 針對所需模型,選取「作業」下方的「API 修訂版本」
    3. 針對您要編輯的模型修訂版本,選取「Operations」(作業) 下方的「Revision Details」(修訂版本詳細資料)
    4. 針對要編輯的 API,選取「Edit Method」(編輯方法)
    5. 選取 API 的「Security Scheme」
    6. 儲存 API。

刪除模型

當您刪除模型 (依序點選 Content > SmartDocs,以及 Drupal 中「Operation」欄位中的「Delete」) 後,該模型就會從 Edge 機構中刪除。也就是說,如果其他入口網站正在參照該模型,就無法再使用該模型。詳情請參閱「關於 SmartDoc 模型和範本」。