使用 SmartDoc 記錄 API

1. 以具備管理員或內容建立權限的使用者身分登入入口網站。
2. 依序選取「設定」>「設定」搜尋和中繼資料 >網址別名 > [Drupal 管理] 選單中的模式。
3. 在「所有 SmartDoc 方法的模式」下方，指定您想要的方式 來產生路徑
4. 選取「儲存設定」。

由於入口網站設有快取功能，因此模型頁面可能不會立即顯示 發布後的畫面如有需要，您可以使用 下列程序：

1. 以具備管理員或內容建立權限的使用者身分登入入口網站。
2. 依序選取「設定」>「設定」Drupal 行政區的 SmartDoc 或前往 Google 試算表選單
3. 按一下「Rebuild SmartDoc 模型快取」。

取消發布節點

您可以隨時取消發布已發布的節點。取消發布節點後， 入口網站使用者。

如何取消發布節點：

1. 以具備管理員或內容建立權限的使用者身分登入入口網站。
2. 選取 內容 >SmartDoc 點選「Drupal」管理選單
3. 找出要取消發布的模型，然後選取下方的「API 修訂版本」 作業
4. 選取要取消發布的節點模型修訂版本。
5. 選取要取消發布的修訂版本中的節點。
6. 在「Update」(更新) 部分選取「Unpublish」(取消發布) 節點。 選項下拉式選單。
7. 按一下「更新」。

查看模型的修訂版本

藉由匯入新的 WADL 檔案或 OpenAPI 規格，建立新的模型修訂版本 或手動建立新的修訂版本。建立新的修訂版本後 ，您就能轉譯並發布修訂版本，取代目前發布的 Drupal 節點

您可以同時轉譯及發布多個修訂版本中的節點。也就是說 模型的五項修訂版本，您可以從任何或所有修訂版本發布節點。不過，發布 模型中的 API 與其他模型的已發布節點相同，就會取消發布 的 API 版本，並替換成最近發布的 API 版本 也能使用 Google Cloud CLI 或 Compute Engine API

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

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

編輯節點

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

您也可以編輯原始 WADL 檔案或 OpenAPI 規格。當您使用 編輯，將 WADL 檔案或 OpenAPI 規格匯入模型做為新的修訂版本 然後按照上述方式轉譯並發布變更。

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

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

或者，您也可以使用 SmartDoc 模型編輯節點：

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

如要刪除節點：

1. 以具備管理員或內容建立權限的使用者身分登入入口網站。
2. 選取 內容 >SmartDoc 點選「Drupal」管理選單
3. 針對您要更新的模型，選取下方的「API 修訂版本」。 作業
4. 選取要發布的模型修訂版本。
5. 選擇「Delete method」(刪除方法)： 該方法的「Operations」(作業) 下拉式選單。
   注意：刪除節點也會將 API 從模型中移除。如果您只有 需要取消發布 API，讓入口網站使用者無法看到這個 API，但並不想將其刪除 請先按照上述方式取消發布節點，

入口網站內建報告，可顯示 SmartDoc 模型不再參照模型的有效方法。報表存取依據： 在 Drupal 選單中選取「報表」，然後選取報表 SmartDoc 節點狀態。

匯出及匯入模型

SmartDoc 可讓您將現有模型匯出成檔案。舉例來說，您可以將 實際工作環境和測試環境然後在暫存室中編輯所有 SmartDoc 環境。準備好發布 API 時，請匯出並匯入測試環境模型 複製到實際工作環境中的模型

匯入模型時，系統會建立新的模型修訂版本。SmartDoc 會嘗試比對現有項目 模型中使用已匯入 API 的 API如果 SmartDoc 偵測到相符結果，匯入作業會更新 Drupal 現有 API 對應的節點如果 SmartDoc 沒有偵測到相符項目，就會 會為 API 建立新的 Drupal 節點。

舉例來說，您有一個 POST API，該 API 對應至 ID 為 91 的 Drupal 節點。然後 會匯入模型，SmartDoc 偵測到已匯入模型的 POST API 與現有模型 POST API。更新 POST API 後，請更新 Drupal 節點 91。如果 SmartDoc 未偵測到 兩者相符，就會以新 ID 建立新的 Drupal 節點。

Drupal 使用下列 API 特性執行比對：

• internalName：內部模型名稱。
• httpMethod：API 的 HTTP 方法，例如 GET、PUT、POST 或 刪除。
• resourcePath：資源路徑。
• query params：API 使用的任何查詢參數。

如果匯入的 API 的四個特性與模型中現有的 API 相符，則 SmartDoc 會更新現有的 Drupal 節點。

匯出的模型會以一個 JSON 物件表示，該物件包含資源項目， 方法。這表示您可以編輯匯出的模型來修改資源或方法，然後 重新匯入模型如果您編輯了 JSON 物件，請勿修改下列欄位：

• revisionNumber
• createdTime
• modifiedTime
• apiRevisionId
• resourceId

如何匯出模型：

1. 以具備管理員或內容建立權限的使用者身分登入入口網站。
2. 選取 內容 >SmartGoogle 文件 in 點選「Drupal」管理選單
3. 找出要匯出的模型，然後選取下方的「匯出」 作業：
4. 將匯出檔案類型選取為 SmartDoc JSON。
5. 按一下 [匯出]。
6. 系統會提示您將檔案儲存到磁碟，或使用編輯器開啟檔案。

如何匯入模型：

1. 以具備管理員或內容建立權限的使用者身分登入入口網站。
2. 選取 內容 >SmartGoogle 文件 in 點選「Drupal」管理選單
3. 找到要匯入的模式，然後選取下方的「匯入」 作業：
4. 在「選擇格式」下拉式選單中，選取「SmartDoc JSON」。
5. 選取位置中的 檔案或網址 上傳類型：
   1. 如果您選取「File」，請瀏覽至 JSON 檔案。
   2. 如果您選取「URL」(網址)，請指定 SmartDoc JSON 檔案的網址。
6. 按一下「Import」，將模型匯入模型。
7. 系統會將您重新導向至模型的資訊頁面，現在您可以在該頁面呈現 模型請注意，匯入作業會建立模型的新修訂版本。
8. 轉譯並發布節點。

編輯 SmartDoc 範本

SmartDoc 範本會定義 Drupal 節點在螢幕上的顯示方式。所有 SmartDoc 可以使用相同的預設範本，您也可以手動自訂 個別模型

SmartDoc 範本包含一個以 Handlebars .hbr 檔案編碼的範本檔案、CSS 檔案 和 JavaScript 檔案使用控點時，大部分的內容都是以變數驅動的嵌入方式 處理常式運算式，例如 &123;&123;body}}。現有 Deployment 帳號代碼是在檔案頂端的註解中提供。如需深入瞭解 請參閱 http://handlebarsjs.com，瞭解使用處理常式自訂範本。

以下各節將說明如何上傳自訂 SmartDoc 範本檔案，供所有人使用 或將新的 API 匯入現有模型時，如何還原 原始預設 SmartDoc 範本檔案，以及如何修改 個別模型

上傳自訂 SmartDoc 範本檔案

您可以上傳自訂 SmartDoc 範本檔案，做為 Handlebars .hbr 檔案，做為 預設範本。

如果您想在建立範本時，使用預設的 SmartDoc 範本檔案做為起點， 自訂 SmartDoc 範本檔案，您可從以下位置下載副本： profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

如何上傳自訂 SmartDoc 範本檔案：

1. 以具備管理員或內容建立權限的使用者身分登入入口網站。
2. 依序選取「設定」 >Drupal 中的 SmartDoc 管理選單
3. 展開網頁的「進階設定」區域。
4. 在「上傳自訂方法範本」下方，按一下「選擇檔案」，然後 找到 Handlebars .hbr 檔案
5. 按一下「上傳」。
6. 按一下「儲存設定」。

還原 預設 SmartDoc 範本檔案

您可以還原預設的 SmartDoc 範本檔案。一旦還原檔案，預設的 SmartDoc 建立新模型或將新 API 匯入現有模型時，會使用範本檔案 模型

如何還原預設 SmartDoc 範本檔案：

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

修改中 想擷取個別模型的 SmartDoc 範本

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

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

1. 以具備管理員或內容建立權限的使用者身分登入入口網站。
2. 選取 內容 >SmartDoc in 點選「Drupal」管理選單
3. 找到要編輯的模式，選取下方的「設定」。 作業：
4. 在「Method Template」區域中，視需要編輯範本。
5. 按一下 [儲存範本]。
6. 瀏覽至 Drupal 節點。您應該會在頁面看到範本變更。

設定 SmartDoc 驗證類型

SmartDoc 中定義的 API 可以是開放性，也就是說 所需的存取權安全的 API 必須在 呼叫 API。

如果是安全的 API，SmartDoc 支援下列類型的驗證：

• 基本驗證：將基本驗證憑證做為 一組使用者名稱和密碼如果您未指定使用 OAuth 做為憑證類型，API 預設採用基本驗證
• OAuth 2.0：第三方服務供應商驗證使用者的 憑證，確認使用者已獲得授權 API，然後核發存取權 產生下一個符記您向受保護的 API 提出 SmartDoc 要求時，SmartDoc 會建置該項要求， 並傳送給服務供應商接著，服務供應商會驗證符記 就表示應用程式尚未過期
• 自訂符記 - 將符記值做為標頭或查詢參數，傳送給每個 請求。

針對每種驗證，您都建立一個安全性配置，用來定義 驗證特性以自訂權杖驗證為例， 安全配置會定義憑證的傳遞方式 (標頭、查詢參數、內文參數) 以及 取得憑證

安全性配置與模型的特定修訂版本相關聯。因此，假設您建立了 新的模型修訂版本，就必須重新定義該修訂版本的安全性配置

在 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 頁面上，SmartDoc 加入了以下按鈕，讓使用者指定 基本驗證憑證：

如果您編輯節點將驗證類型設為 OAuth，SmartDoc 會將 下列按鈕：

如果是自訂符記，SmartDoc 會加入下列項目：

設定中 基本驗證

如果您使用 API 進行基本驗證，則只需在 WADL 中指定 <apigee:authentication> 標記 可用以建立模型

如何將基本驗證套用至從 WADL 檔案以外的來源建立的方法：

1. 以具備管理員或內容建立權限的使用者身分登入入口網站。
2. 選取 <br>Google 文件 點選「Drupal」管理選單
3. 選取所需模型下方的「API 修訂版本」。 作業
4. 找到您要編輯的模型修訂版本，選取「安全性」 設定「作業」「作業」。
5. 選取「Add Security Scheme」。
6. 指定安全性配置的名稱。
7. 選取「基本」做為「類型」。
8. 選取 [提交]。
9. 針對模型中的每個方法，編輯該方法的「安全配置」設定 調整到基本配置
   1. 選取 <br>Google 文件 點選「Drupal」管理選單
   2. 選取所需模型下方的「API 修訂版本」。 作業
   3. 針對您要編輯的模型修訂版本，選取「修訂版本」 作業部分詳細說明。
   4. 針對您要編輯的 API，選取「Edit Method」(編輯方法)。
   5. 選取 API 的「Security Scheme」(安全性配置)。
   6. 儲存 API。

設定中 OAuth 2.0 驗證

您可以將模型設為在 SmartDoc 中使用 OAuth 2.0，而非預設的基本文件 驗證。您會在兩個位置設定 OAuth：

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

如何啟用 OAuth：

1. 以具備管理員或內容建立權限的使用者身分登入入口網站。
2. 選取 <br>Google 文件 點選「Drupal」管理選單
3. 針對所需模型，選取「作業」下方的「API 修訂版本」。
4. 找到您要編輯的模型修訂版本，並選取「安全性設定」下方的「安全性設定」 作業：
5. 選取「Add Security Scheme」。
6. 指定安全性配置的名稱。
7. 選取「OAuth 2.0」做為「Type」。
8. 設定「Grant Type」。
9. 在「授權網址」欄位中輸入值。授權 網址可用來取得存取權杖。
10. 將「Authorization Verb」設為 GET 或 POST。
11. 輸入「Access Token URL」(存取權杖網址)。存取權杖網址就是用於 交換要求權杖來取得存取權杖
12. 輸入「Access Token param name」。
13. 使用 In 指定傳遞權杖的方式：Header、 Query 或 Body.
14. 設定 OAuth 範圍。
15. 選取 [提交]。
16. 選取 <br>Google 文件 點選「Drupal」管理選單
17. 針對模型，請選取「Operations」(作業) 中的「Settings」(設定) 。
18. 在用戶端 ID 和 用戶端 Secret。
19. 選取「儲存範本驗證設定」。
20. 針對模型中的每個方法，編輯該方法的「安全配置」設定 您的 OAuth 安全性配置。
    1. 選取 <br>Google 文件 點選「Drupal」管理選單
    2. 選取所需模型下方的「API 修訂版本」。 作業
    3. 針對您要編輯的模型修訂版本，選取「修訂版本」 作業部分詳細說明。
    4. 針對您要編輯的 API，選取「Edit Method」(編輯方法)。
    5. 選取 API 的「Security Scheme」(安全性配置)。
    6. 儲存 API。

設定自訂權杖驗證

您可以將模型設為使用自訂權杖驗證。

如何啟用自訂權杖：

1. 以具備管理員或內容建立權限的使用者身分登入入口網站。
2. 選取 <br>Google 文件 點選「Drupal」管理選單
3. 選取所需模型下方的「API 修訂版本」。 作業
4. 找到您要編輯的模型修訂版本，選取「安全性」 設定「作業」「作業」。
5. 選取「Add Security Scheme」。
6. 指定安全性配置的名稱。
7. 選取「Apikey」Apikey做為「Type」Apikey。
8. 設定包含符記的「ParamName」。
9. 使用 In 指定將 符記：Header、Query、 或 Body。
10. 選取 [提交]。
11. 針對模型中的每個方法，編輯該方法的「安全配置」設定 並套用至權杖配置
    1. 選取 <br>Google 文件 點選「Drupal」管理選單
    2. 選取所需模型下方的「API 修訂版本」。 作業
    3. 針對您要編輯的模型修訂版本，選取「修訂版本」 作業部分詳細說明。
    4. 針對您要編輯的 API，選取「Edit Method」(編輯方法)。
    5. 選取 API 的「Security Scheme」(安全性配置)。
    6. 儲存 API。

刪除模型

刪除模型後 (依序點選「內容」>「SmartDoc」，前往「刪除」 「作業」欄位時，模型就會從 Edge 機構中刪除。也就是說 其他入口網站參照模型，該模型已無法使用。如需更多資訊 請參閱「關於 SmartDoc 模型和範本」。