使用新的視覺化 SwaggerHub 編輯器編寫 OpenAPI 規格文件

  2019 年 4 月 23 日

我們很高興宣布新的增強功能,讓組織更容易編寫 API 文件並在 SwaggerHub 中分享公開的 API 文件。

用於編寫 OAS 定義文件的新視覺化編輯器

現在,您可以編輯 API 資訊和中繼資料,而無需在 SwaggerHub 中直接使用 YAML 編輯器。

新的視覺化編輯體驗非常適合可能不直接了解 YAML 語法的團隊成員,或者需要建構 OAS 定義中重要細節(如 API 資訊(標題、描述、授權、聯絡資訊)或操作中繼資料(摘要、描述、標籤))的技術寫手。

在視覺化編輯器中所做的變更將自動與 YAML 程式碼編輯器同步,並在 UI 視圖中即時視覺化。該編輯器還支援 Markdown 語法,允許將不同的格式和樣式應用於技術文件,這些文件可能難以在 YAML 編輯器中描述。

注意:這是 SwaggerHub 中視覺化編輯器的第一個版本。未來,我們將新增增強功能,以描述端點、標頭、主體等。

存取新的視覺化編輯器

若要切換至視覺化編輯器,請在 SwaggerHub 編輯器的側邊欄中按一下「顯示視覺化編輯器」。如果游標位於 YAML 程式碼中的特定操作內,視覺化編輯器將開啟該操作。

Open-Visual-Editor.png

在左側的「導覽」面板中選取一個項目。如果「導覽」面板已隱藏,請按一下側邊欄中的「顯示視覺化編輯器」圖示以顯示它。

visual-editor-api-info.png

探索新的視覺化編輯器

將公司標誌和品牌新增至 Swagger UI 文件

現在,組織可以將自己的品牌新增至在 SwaggerHub 中託管的 API 文件。新的可自訂文件功能非常適合利用 SwaggerHub 分享外部 API 文件的組織。

新的功能可讓組織上傳公司標誌,以取代標準的 SwaggerHub 標誌,並自訂標頭顏色以符合其企業品牌。

Custom-Docs-Example.png

文件品牌功能適用於團隊和企業方案的組織。

存取新的文件品牌功能

組織擁有者可以在組織設定的「文件品牌」頁面上設定品牌選項

  1. 按一下您的使用者名稱並選取「設定」。
  2. 切換至「我的組織」索引標籤。
  3. 在左側的側邊欄中選取「文件品牌」。

Docs-Branding.png

探索新的文件品牌功能

與 Azure DevOps Services 整合

新的 Azure DevOps Services 整合功能可讓您將 API 定義、自動產生的伺服器程式碼或用戶端 SDK 與 Azure DevOps Services(以前稱為 Visual Studio Team Services 或 VSTS)中現有的 Git 儲存庫同步。每次您在 SwaggerHub 中儲存 API 時,整合功能都會更新指定儲存庫中的程式碼。

與 Azure DevOps Services 的整合是新增至 SwaggerHub 的最新原始碼控制整合功能,以及現有的 GitHub、GitLab 和 Bitbucket 整合功能。

存取新的整合功能

  1. 在 SwaggerHub 編輯器中開啟您的 OAS 2.0 或 OAS 3.0 定義。
  2. 如果 API 有多個版本,請選取您要與 Azure DevOps Services 中的儲存庫同步的版本。

Open-SwaggerHub-Integrations.png

  1. 按一下 API 名稱以開啟 API 資訊面板。
  2. 在「API 資訊」面板中,切換至「整合」索引標籤,然後按一下「新增整合」。

Add-New-Integration.png

  1. 從整合清單中選取「Azure DevOps Services」。

探索 Azure DevOps Services 整合

開始使用 SwaggerHub

所有這些最新更新都在 SwaggerHub 團隊和企業方案中提供。 登入並親自試用立即開始免費試用