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

GSoD 2020：改善 API 參考體驗

作者：Philippe Martin |

編者按：在我三年半前加入 Kubernetes 文件團隊以來，更好的 API 參考一直是我的目標。Philippe 取得了巨大的成功。然而，Philippe 在這個專案中不僅提供了更好的 API 參考，他還體現了 Kubernetes 社群最優秀的一面：透過協作實現卓越，以及使社群自身變得更好的過程。感謝 Google Season of Docs 使 Philippe 的工作成為可能。—Zach Corleissen

引言

Google Season of Docs 專案將開源組織和技術作家聚集在一起，緊密合作完成一個特定的文件專案。

我被 CNCF 選中，負責 Kubernetes 文件工作，特別是讓 API 參考文件更易於訪問。

我是一名軟體開發者，對文件系統有著濃厚的興趣。20世紀90年代末，我開始將 Linux-HOWTO 文件翻譯成法語。不知不覺中，我學會了文件系統。最終，我寫了一個 Linux-HOWTO 來幫助文件編寫者學習當時用於編寫文件的語言——LinuxDoc/SGML。

不久之後，Linux 文件採用了 DocBook 語言。我幫助一些作者用這種格式重寫他們的文件；例如，《高階 Bash 指令碼指南》。我還參與了 GNU `makeinfo` 程式的工作，添加了 DocBook 輸出，使得將 GNU Info 文件轉換為 DocBook 格式成為可能。

背景

Kubernetes 網站使用 Hugo 構建，文件以 Markdown 格式編寫在網站倉庫中，並使用了Docsy Hugo 主題。

現有的 API 參考文件是一個從 Kubernetes OpenAPI 規範生成的巨大 HTML 檔案。

就我而言，我一直希望透過以下方式讓 API 參考更易於訪問：

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

大約一年前，我開始著手開發生成當前唯一 HTML 頁面的生成器，以新增 DocBook 輸出，這樣 API 參考就可以首先以 DocBook 格式生成，然後透過 DocBook 處理器轉換為 PDF 或其他支援的格式。最初的結果是一些API 參考的電子書檔案和一本自出版的紙質書。

後來我決定給這個生成器新增另一個輸出，以生成 Markdown 檔案並建立一個帶有 API 參考的網站。

當 CNCF 提議一個 Google Season of Docs 專案來處理 API 參考時，我提交了申請，然後成功匹配。

專案

swagger-ui

提出此專案的 CNCF 成員最初的想法是測試`swagger-ui` 工具，並嘗試使用此標準工具來文件化 Kubernetes API 參考。

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

通常，開發者透過使用特定的 HTTP 動詞呼叫帶有特定引數的端點並等待響應來使用 API。`swagger-ui` 介面就是為此用途而構建的：該介面顯示端點列表及其關聯的動詞，以及每個端點的引數和響應格式。

Kubernetes API 大部分時候以不同的方式使用：使用者建立包含 YAML 格式資源定義的清單檔案，並使用 `kubectl` CLI 將這些清單“應用”到叢集。在這種情況下，最重要的資訊是作為引數和響應的結構（Kubernetes 資源）的描述。

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

Markdown 頁面

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

主要改動包括：

  • 使用 Go 模板來表示輸出頁面，這樣非開發者就可以在不編輯生成器程式碼的情況下調整生成的頁面
  • 建立一個新的自定義短程式碼，以便輕鬆從網站內部建立指向 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.club.tw/docs/reference/ 訪問。

未來工作

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

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

鳴謝

我要感謝我的導師 Zach Corleissen 以及首席作家 Karen Bradshaw、Celeste Horgan、Tim Bannister 和 Qiming Teng，他們在整個賽季中指導了我。他們都非常鼓勵我，並給了我大量寶貴的建議。