1.選擇靜態站點生成器

如果您想要強大的控制力來創建您需要的復雜功能(也許您想構建自定義主題或構建具有獨特品牌的文檔站點)，請使用靜態站點生成器，例如Hugo、Sphinx或Jekyll。如果您有嚴重的文檔需求(也許您從 DITA 世界遷移過來并習慣于更強大的工具)，您將需要一個可以深入到您想要的平臺。Jekyll、Sphinx 和 Hugo 在平臺中提供了這種深度。

當然，這種能力和控制需要更復雜的平臺和學習曲線，但您可以從一個現成的主題輕松開始，然后根據需要進入自定義開發。

如果您沒有 Web 開發技能并且不想修補主題或其他代碼開發，請選擇Readme.com或Netlify CMS等解決方案(不過，使用 Netlify CMS，您仍然必須選擇一個主題)。自述文件為您的 API 文檔站點提供了現成的設計，消除了設計主題和確定托管/部署的需要。這可以為您節省大量時間和精力。

意識到在實施解決方案時，您可能會花費四分之一的時間(在項目時間間隔的幾個月內)定制您的主題并處理文檔工具。如果您不想在工具上花費太多時間，Readme 是一個不錯的選擇。

如果您想使用靜態站點生成器，您應該選擇哪一個——Jekyll、Hugo、Sphinx 或其他一些?Sphinx 具有最面向文檔的功能，例如搜索、PDF、交叉引用鏈接和語義標記。如果這些功能很重要，請考慮 Sphinx。

然而，選擇 Jekyll 或 Hugo 而不是 Sphinx 確實有理由，因為他們的社區超出了文檔組。Sphinx 被設計為一個文檔平臺，因此它的受眾往往更小眾。文檔工具幾乎從來沒有像更通用的 Web 開發工具那樣具有社區規模。因此，與 Jekyll 或 Hugo 的權衡是，盡管它們缺乏一些更好的文檔功能(交叉引用、搜索、PDF、語義標記)，但從長遠來看，它們可能擁有更多的社區和動力。盡管如此，如果您必須為搜索、PDF 和翻譯(這些是可行的，但不是開箱即用的)找出解決方案，這可能會讓您陷入困境。

標記也是一個考慮因素。如果您已將選擇范圍縮小到使用 reStructuredText 的 Sphinx 或使用 Markdown 的 Jekyll/Hugo，那么要問的一個問題是貴公司的工程師是否會使用 reStructuredText 進行寫作(假設工程師會寫作)。如果他們用 reStructuredText 編寫，很好，由于reStructuredText的語義優勢，Sphinx 可能更適合文檔項目。但如果工程師堅持使用 Markdown，那么也許 Jekyll 或 Hugo 會是更好的選擇。

2.選擇托管和部署平臺

在確定要使用的靜態站點生成器的范圍后，接下來考慮托管和部署選項(提供持續交付)。如果您決定使用 Sphinx，請考慮使用Read the Docs。如果您已決定使用 Jekyll，請探索GitHub Pages、CloudCannon、Netlify或Aerobatic。如果您已決定使用 Hugo，請探索Netlify或Aerobatic。通過使用這些平臺之一，您可以減輕維護服務器和部署站點的巨大負擔。

通常，在公司內部，工程團隊管理和控制服務器基礎設施。僅使用內部資源設置和維護您自己的文檔服務器可能是一筆相當大的費用和頭痛。可能需要數月(如果不是數年)才能讓工程師在服務器上為您提供空間，即使他們這樣做，它也可能無法提供您需要的一半功能(例如持續交付和 CLI)。這就是為什么我盡可能推薦這些第三方托管和部署選項的原因。

維護自己的服務器不是您想要從事的業務，而這些第三方平臺使您能夠更有效率。通過服務器的持續交付消除發布的麻煩將簡化您的生活。另一方面，如果您有一個工程工具支持小組，并且他們對支持技術文檔有足夠的帶寬和興趣，則使用內部工具可以促進與您工作中可用的其他工具(例如驗證測試)的集成。

如果您的公司更喜歡建立自己的發布渠道，那么在您走這條路之前，請先了解內部解決方案將提供哪些功能。探索這些第三方主機和部署選項的一些優勢，并檢查內部解決方案是否具有足夠的同等性和長期支持。如果你有強大的工程支持，那就太好了，你可能處于一個很好的位置。但如果工程師幾乎不給你時間，請考慮第三方解決方案。請參閱案例研究：將工具切換為 docs-as-code，了解我在這條路線上的經驗。

如果您沒有第三方主機和部署選項的預算，也沒有內部工程資源，請考慮部署到AWS S3 存儲桶。Jekyll 有一個名為S3_website的插件，可以輕松部署到 S3。它不是持續交付模型，但也不涉及每次要發布時上傳整個站點輸出。S3_website 插件查看輸出中的更改并將這些更改與 S3 上的文件同步。(但是，我承認，一旦您習慣于通過簡單地提交到您的存儲庫來進行持續交付發布，就很難考慮以任何其他方式發布。)

另外，請注意，即使您沒有使用 Jekyll，您也可以使用GitHub Pages作為任何靜態站點生成器輸出的免費發布主機。您只需在本地構建文件，然后將構建的文件推送到支持 GitHub 頁面的存儲庫。使用這種方法，您不會讓服務器執行構建過程，但您仍然可以通過命令行處理該過程。在 GitHub 上免費托管您的文檔，無論使用何種工具，都特別方便。

3.決定如何解析 OpenAPI 規范

該OpenAPI的規范也可能是你考慮的工具的一個重要因素。您將如何顯示所有端點參考文檔?與其創建您自己的模板或手動定義這些參考部分，建議您使用可以讀取和解析 OpenAPI 的工具作為您的參考文檔。沒有多少獨立的文檔工具可以輕松地合并和顯示 OpenAPI 規范(目前)，因此也許最好的選擇可能是鏈接到或嵌入Swagger UI與您的文檔(假設您沒有用于更深入集成的 UX 資源)。