本文已超過一年。較舊的文章可能包含過時的內容。請檢查頁面中的資訊自發布以來是否已變得不正確。

GSoD 2020：改善 API 參考體驗

作者：Philippe Martin |

編輯註記：自從三年半前我加入 Kubernetes 文件團隊以來，改善 API 參考文件一直是我的目標。Philippe 取得了驚人的成功。然而，Philippe 在這個專案中體現了 Kubernetes 社群的最佳特質：透過協作追求卓越，以及使社群本身變得更好的流程，這不僅僅是更好的 API 參考文件。感謝 Google Season of Docs，讓 Philippe 的工作成為可能。—Zach Corleissen

簡介

Google Season of Docs 專案將開放原始碼組織和技術寫作者聚集在一起，緊密合作於特定的文件專案。

我被 CNCF 選中從事 Kubernetes 文件工作，特別是為了讓 API 參考文件更易於存取。

我是一名軟體開發人員，對文件系統非常感興趣。在 90 年代後期，我開始將 Linux-HOWTO 文件翻譯成法文。從一件事到另一件事，我了解了文件系統。最終，我撰寫了一份 Linux-HOWTO，以幫助文件編寫者學習當時用於編寫文件 LinuxDoc/SGML 的語言。

不久之後，Linux 文件採用了 DocBook 語言。我協助一些作者以這種格式重寫他們的文件；例如，《Advanced Bash-Scripting Guide》。我也參與了 GNU makeinfo 程式，以新增 DocBook 輸出，使將 GNU Info 文件轉換為 Docbook 格式成為可能。

背景

Kubernetes 網站 是使用 Hugo 從 website 儲存庫 中以 Markdown 格式撰寫的文件建構而成，並使用 Docsy Hugo 主題。

現有的 API 參考文件是從 Kubernetes OpenAPI 規範產生的大型 HTML 檔案。

就我而言，我希望在一段時間內讓 API 參考文件更易於存取，透過

  • 為每個 Kubernetes 資源建構個別且獨立的頁面
  • 調整格式以適合行動裝置閱讀
  • 重複使用網站的資產和主題來建構、整合和顯示參考頁面
  • 允許搜尋引擎參考頁面的內容

大約一年前，我開始研究建構目前單一 HTML 頁面的產生器，以新增 DocBook 輸出，以便可以先以 DocBook 格式產生 API 參考文件，然後再以 PDF 或 DocBook 處理器支援的其他格式產生。第一個成果是一些 API 參考文件的電子書檔案 和一本自動編輯的紙本書。

稍後我決定為此產生器新增另一個輸出，以產生 Markdown 檔案並建立 具有 API 參考文件的網站。

當 CNCF 為 Google Season of Docs 提出一個關於 API 參考文件的工作專案時，我提出了申請，並且成功配對。

專案

swagger-ui

提出此專案的 CNCF 成員的第一個想法是測試 swagger-ui 工具，嘗試使用此標準工具記錄 Kubernetes API 參考文件。

由於 Kubernetes API 比許多其他 API 大得多，因此有必要編寫一個工具來按 API 群組分割完整的 API 參考文件，並在文件網站中插入多個 swagger-ui 元件，每個 API 群組一個。

一般而言，API 由開發人員使用，透過使用特定的 HTTP 動詞呼叫端點、使用特定的參數並等待回應。swagger-ui 介面是為此使用情境而建構的：介面顯示端點及其相關動詞的清單，以及每個端點的參數和回應格式。

Kubernetes API 在大多數情況下以不同的方式使用：使用者建立包含 YAML 格式資源定義的 manifest 檔案，並使用 kubectl CLI 將這些 manifest 套用 至叢集。在這種情況下，最重要的資訊是用作參數和回應的結構描述 (Kubernetes 資源)。

由於這種特殊性，我們意識到很難調整 swagger-ui 介面以滿足 Kubernetes API 使用者的需求，因此放棄了這個方向。

Markdown 頁面

專案的第二階段是調整我為建立 k8sref.io 網站所做的工作，將其納入官方文件網站。

主要變更是

  • 使用 go-templates 來表示輸出頁面，以便非開發人員可以在不必編輯產生器程式碼的情況下調整產生的頁面
  • 建立新的自訂 shortcode，以便輕鬆地從網站內部建立連結到 API 參考文件的特定頁面
  • 改進 API 參考文件各章節之間的導覽
  • 將產生器的程式碼新增至包含不同參考產生器的 Kubernetes GitHub 儲存庫

所有討論和完成的工作都可以在網站 pull request #23294 中找到。

將產生器程式碼新增至 Kubernetes 專案發生在 kubernetes-sigs/reference-docs#179 中。

以下是要包含在官方文件網站中的新 API 參考文件的功能

  • 資源已分類，分為工作負載、服務、配置和儲存、身份驗證、授權、策略、擴展、叢集等類別。此結構可透過簡單的 toc.yaml 檔案 進行配置
  • 每個頁面都在第一層顯示相關資源；例如：Pod、PodSpec、PodStatus、PodList
  • 大多數資源頁面內嵌相關定義；例外情況是當這些定義是多個資源共用，或是複雜到無法內嵌顯示時。使用舊方法，您必須點擊超連結才能閱讀每個額外細節。
  • 一些廣泛使用的定義，例如 ObjectMeta，會在特定頁面中說明
  • 必要欄位會被標示，並放在最前面
  • 資源的欄位可以使用 fields.yaml 檔案 進行分類和排序
  • map 欄位會被標示。例如，Pod 的 .spec.nodeSelector 是 map[string]string，而不是 object，使用 x-kubernetes-list-type 的值
  • 修補策略會被標示
  • apiVersion 和 kind 顯示值，而不是 string 類型
  • 在參考頁面的頂端，頁面會顯示從 Go 程式使用這些資源所需的 Go 匯入路徑。

目前工作暫停，等待 1.20 版本發布。當版本發布完成並整合工作後，API 參考文件將在 https://kubernetes.dev.org.tw/docs/reference/ 上提供。

未來工作

有一些需要改進的地方，特別是

  • 一些 Kubernetes 資源是深度巢狀的。內嵌這些資源的定義使它們難以理解。
  • 建立的 shortcode 使用頁面的 URL 來參考資源頁面。如果文件編寫者可以透過群組和名稱來參考資源，將會更容易。

感謝

我要感謝我的導師 Zach Corleissen 和主要作者 Karen Bradshaw、Celeste Horgan、Tim Bannister 和 Qiming Teng，他們在整個專案期間指導我。他們都非常鼓勵我，並給了我許多很棒的建議。