更新 SmartDocs

在將入口網站網址提供給 API 使用者之前,請先確認 SmartDocs API 參考說明文件正確無誤,且 API 的運作與說明文件一致。在您查看產生的參考說明文件並進行測試時,可能會發現有內容需要變更。

本頁說明:

  • SmartDocs API 參考說明文件
  • SmartDocs 如何使用 Cloud Endpoints Frameworks 建立的 openapi.json 檔案中的欄位產生 SmartDocs
  • 如何產生 SmartDocs 系統會針對每項工作提供完成該項工作所需的 Cloud Identity and Access Management 角色基本規定。如要進一步瞭解 Cloud IAM 權限,請參閱以下內容:

先決條件

本頁假設您已建立入口網站

關於 SmartDocs API 參考說明文件

當您依照以下說明新增 API 管理時:

Endpoints Frameworks 會為您的 API 建立 OpenAPI 文件。每次您將 OpenAPI 文件部署至 Endpoints 服務時,SmartDocs 都會為您的入口網站產生 API 參考說明文件。SmartDocs UI 以先進的 UI 元件程式庫 Angular Material 為基礎。開發人員可以查看您的 SmartDocs API 參考說明文件,並使用「試用這個 API」小工具與您的 API 互動,完全不須離開 API 說明文件。

關於用於產生 SmartDocs 的欄位

當您依照以下說明新增 API 管理時:

Endpoints Frameworks 會為您的 API 建立 JSON 格式的 OpenAPI 文件。當您使用 gcloud endpoints services deploy 部署 OpenAPI 文件時,SmartDocs 會依據 Endpoints Frameworks 建立的 OpenAPI 文件,為您的入口網站產生更新過的 API 參考說明文件。

Endpoints Frameworks 並不會在為您 API 建立的 OpenAPI 文件中加入說明。在您為 API 的使用者提供入口網站的網址之前,我們建議您在 OpenAPI 文件中新增有關 API 的說明、方法以及參數等。

若您不熟悉 OpenAPI,請先查看 Swagger 基本結構網站,其中提供範例 OpenAPI 文件並簡要說明檔案的每個區段。詳情請參閱 OpenAPI 規範

如同在中繼資料區段所說明,description 欄位的值可包含多行指令並且支援 GitHub Flavored Markdown

如要幫助使用者瞭解如何在您的 API 中使用方法,最佳做法是新增一個 description 欄位到參數區段以及要求主體

您的 OpenAPI 文件會包含類似以下的內容:

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "example-project-12345.appspot.com"
 },
 "host": "example-project-12345.appspot.com",

這些欄位在入口網站中顯示的值如下所示:

  • title:這個標題值會顯示在您入口網站首頁列出專案 API 的部分、API 首頁 (會附加「documentation」字樣),以及 API 標題列中。

  • host:主機的值,同時也是您的 Endpoints 服務名稱。這個值會顯示在您入口網站首頁列出專案 API 的部分,以及「Settings」(設定) 頁面「API」分頁裡的下拉式清單中。

  • version:API 入口網站網址所用的主要版本號碼。

您可以變更 title 欄位的值並且新增一個 description 欄位供 API 使用,例如:

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "Endpoints Frameworks Example",
  "description": "A simple Cloud Endpoints Frameworks API example."
 },
 "host": "example-project-12345.appspot.com",

重新產生 SmartDocs

如要重新產生參考說明文件,請執行下列操作:

  1. 針對 Endpoints Frameworks 所產生的 openapi.json 檔案進行變更。

  2. 重新部署 openapi.json

    gcloud endpoints services deploy openapi.json
    
  3. 重新整理您的入口網站頁面。

  4. 如果您後續須重新產生 openapi.json 檔案,請將修改後的 openapi.json 檔案儲存至不會遭到覆寫的位置。如果您對 API 做出變更並重新產生 openapi.json 檔案,就必須將新產生的 openapi.json 中的變更與先前所做變更進行合併。

如要進一步瞭解指令,請參閱 gcloud endpoints services deploy

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
App Engine 適用的 Cloud Endpoints Frameworks
需要協助嗎?請前往我們的支援網頁