本文主要內容：API文檔提供了預測客戶成功的關鍵路徑；在代碼附近的文檔上進行協作可以更好地檢查代碼和文檔文件，提高自動化效率，並專門針對文檔進行質量測試；提供通用文檔框架，標準，自動化和工具，以提高團隊效率。
編寫文檔有時候會非常枯燥乏味，但優秀的文檔是增加API被採用的一個很好的前提。編寫出色的文檔與編寫代碼一樣需要嚴謹。隨着API的質量逐漸成爲產品增長的指標，您的文檔比以往任何時候都更加重要，優秀的文檔很大程度上代表創建了成功的API。API定義和文檔常常結合在一起，雖然今天的API規範越來越多地作爲GitHub中的代碼進行管理，但API文檔並非如此。所以需要讓我們對此進行更改，以便在GitHub和相關代碼庫中編寫和管理API文檔（包括相關網站）的標準。
通過儘可能靠近代碼和API定義協作編寫文檔，您可以自動執行文檔測試，構建和部署。API的文檔通常構建爲網站，因此如果在分段構建期間就可以進行鏈接檢查等測試。這種方法提供了許多好處：經過測試的文檔構建；支持連續發佈；支持對文檔內容和代碼的評論；多個輸出（包括經過測試的代碼示例）；文檔的發佈管理（如API的早期訪問版本）或增量更改和添加到發佈了API，並防止代碼合併。
文檔持續集成/交付
對於REST API文檔，三個框架以網頁的形式提供文檔輸出，其中許多是交互式的。這些是OpenAPI（Swagger），RESTful API建模語言（RAML）和API藍圖。OpenAPI（以前稱爲Swagger）基於JSON輸出，由於YAML是JSON的超集，因此您可以交換描述API的源文件。RAML是一種基於YAML的語言，用於描述REST API。API Blueprint使用Markdown，也可以遵循GitHub Flavored Markdown語法。
許多編程語言都有一個文檔框架，可以很好地與代碼本身集成。通常，這些是靜態站點生成器，例如Jekyll for Ruby和Sphinx for Python。文檔的源文件是Markdown或reStructured Text（RST）。使用這些靜態站點生成器，您可以創建漂亮的文檔站點。事實上，GitHub上有一系列鏈接到漂亮的文檔網站，其中包括Stripe API文檔站點和Basho文檔 - 這些是獲得美觀和實用程序最高分的示例API站點。
由於可以使用腳本轉換這些文檔源文件和網站配置文件，因此您可以使用與代碼相同的構建作業來持續構建文檔。通過從靜態目錄複製平面文件來部署Jekyll站點，因此您可以存儲腳本以使用其他構建文件在代碼存儲庫中構建站點。您還可以使用簡單的鏈接檢查程序在部署站點之前測試任何損壞的鏈接。HTMLProofer庫是一個爲此而編寫的Ruby庫。
GitHub提供的部署機制稱爲GitHub Pages。您可以選擇觸發文檔網站部署。您可以從gh-pages分支，主分支自動化構建，或始終從主分支上的/ docs目錄部署文檔。雖然您可以部署到自定義域名，但GitHub頁面的一個限制是您不能直接通過HTTPS提供服務，但作爲免費服務，它是一個很好的起點。對於生產網站，您可以從GitHub部署到具有所需安全要求的雲服務器或VPS。而GitHub Enterprise是GitHub的內部部署，用於內部部署，提供類似的託管站點功能。
爲什麼要像代碼一樣處理文檔
當成果已經可以交付給開發人員時，那與開發人員一起寫文檔會很有效。API文檔任務爲處理代碼等文檔的原因和時間提供了一個很好的示例。特別是在設計API或向API添加功能時的關鍵設計點，開發人員可以像文檔代碼一樣貢獻文檔。
例如，在自動化參考信息時，您可以獲得即時性和準確性，並通過在GitHub，Bitbucket或GitLab等社交編碼系統中協作編寫來獲得貢獻，質量和同理心。此外，API的最大成功指標之一是文檔的準確性和有用性。當您的團隊處理代碼等API文檔時，以下是一些特定的好處，下面將對此進行更深入的探討：
1.協作效率
可以爲開發人員和文章協作編寫者兩個角色提供有價值的信息。開發人員希望爲類似於自己的受衆撰寫文章，爲讀者提供經驗分享。協作編寫者有一個特殊的訣竅來組織信息，文筆更好，並以適當的順序揭示概念和參考信息。如果在同一個存儲庫中協同工作可以提供溝通的效率，增加教學和被教學的機會。
2.貢獻收益
當沒有專門的技術寫作團隊時，你可以擴大貢獻者的數量，即使API本身不是公共文檔的公共文件。或者，您可以通過在GitHub或Bitbucket等版本控制系統中提供開源文檔存儲庫，從最終用戶自己獲得更多貢獻。當文檔與代碼位於同一存儲庫中時，任何感興趣的開發人員（包括客戶）都可以訂閱拉取請求的通知。
3.跟蹤文檔中的錯誤
要獲得更高質量的文檔，請提供直接在輸出頁面上報告文檔錯誤的方法。正如萊納斯定律所述，“給予足夠的眼球，所有的錯誤都是淺薄的”。通過爲這些眼球提供報告錯誤的位置，您可以爲文檔提供更多類似代碼的質量跟蹤。此外，通過問題跟蹤制定的指標，您可以衡量文檔的質量，並確保在需要解決這些錯誤時可使用指標來判斷。
4.對文檔和代碼的評論
在查看代碼中包含的文檔時，審閱者可以在文檔不足時阻止對代碼的更改。該審查指南爲團隊提供了使文檔具有高質量的能力，即使它們必須與快速變化的代碼同步。
將文檔源文件放在像GitHub這樣的開放系統中可以使內容具有開放貢獻，類似於開源代碼。在OpenStack中，大量的開源雲項目，文檔貢獻過程與代碼貢獻過程相同。編寫者和開發人員在訪問僅文檔存儲庫（僅代碼存儲庫）時具有相同的協作工具和背景知識。
當您的API定義需要一定程度的守門或小心防護時，您還可以考慮將GitHub Enterprise用於內部API文檔。您的團隊仍然可以在內部獲得協作優勢，而無需向全世界打開您的文檔和代碼。
5.部署和發佈
處理代碼等文檔時，意識到您正在將構建與部署分離。通過這種方式，您可以對文檔的早期草稿進行審覈，並且在文檔構建部署併發布到網站之前，它都可以隨時進行修正。或者，您可以選擇不斷髮布一些文檔以跟上代碼。例如，您可以選擇編寫敘述性文檔和教程，這些文檔和教程會隨着每個補丁集添加而不斷髮布。但對於像OpenAPI規範這樣的合同文檔，只有在考慮在特定版本下發布API時，才能部署新文檔。
6.測試和構建文檔
通過爲評論提供匹配的分段構建和向讀者交付的生產構建，您可以確信您對構建的文檔的審覈滿足用戶需求。請參閱以下部分中的示例。
docs的示例測試
您可以測試文檔源文件的質量以及是否構建。您還可以檢查拼寫或語法，但也可以通過人爲進行檢查。但測試文檔的目的是減輕人類審閱者的審查負擔，自動化能節省時間，以便可以編寫，發佈和發佈更多文檔文件。
鏈接檢查
對於許多靜態站點生成器，有專門用於檢查站點中所有鏈接的庫。例如，在檢查像docslikecode.com這樣的Jekyll網站上的鏈接時，Travis CI工作很簡單：
#!/usr/bin/env bash
set -e # halt script on error
bundle exec jekyll build
bundle exec htmlproofer ./_site
通過這種類型的測試，人工審閱者不必花時間點擊新補丁中的每個鏈接。如果需要更新外部鏈接，那麼這個測試的結果會通知您。如果內部鏈接因修補程序本身而中斷，則系統可以在人爲查看修補程序之前修復它。
JSON格式
使用REST API文檔，請求和響應通常是JSON文件，對於閱讀文檔的人在將自己的環境與文檔進行比較時非常有價值。在讀者需要複製和粘貼請求的情況下，正確格式化示例至關重要。在OpenStack中，我們有一組包含JSON測試器和格式化程序的通用文檔工具。通過對傳入的修補程序對文檔文件運行此測試，讀者可以確定所包含的JSON文件是否格式正確。此外，當它們可以在本地運行簡單命令以確保JSON格式正確時，它可以使貢獻者更容易創建補丁。
驗證的請求和響應
高級文檔測試可以檢查文檔中包含的示例請求和響應。用查看代碼文件相同的方式查看文檔文件時，準確性通常是最高值。因此，通過針對正常工作的API端點測試示例，您可以證明這些示例也適用於實際情況。這種類型的驗證提供了每次都可用的成功文檔示例，因爲只有它們通過驗證測試，它們才被髮布。
建立檢查
自動化文檔測試可以節省讀者的時間，因爲他們不必自己構建文檔來查看輸出。此外您可以測試損壞的鏈接或不正確格式化的JSON文件的構建。對於任何奇怪的問題，查看源文檔和輸出文檔都很有幫助。
結論
在與代碼庫相同的倉庫中協同處理文檔，可以更好地爲客戶提供服務，無論他們是組織的內部還是外部。通過將API文檔視爲代碼，您可以找到自動化途徑，提高效率，加快文檔構建，在文檔中構建成功示例。
自動化測試功能除了能減少開發的時間之外，自動化測試還有助於進行項目流程測試，最近因爲一直在使用EOLINKER進行API研發管理，因此推薦自動化測試功能，因爲它支持UI模式和高級模式，可以實現不同類型的自動化測試項目，比如登錄驗證就可以用UI模式，高級模式則用來測試較爲複雜的項目，對比之前效率高了不少，對API自動化測試等方面有興趣的小夥伴前往瞭解下哦！https://www.eolinker.com
作者：Anne Gentle，思科的技術產品經理；
原文標題：Always Be Publishing: Continuous Integration & Collaboration in Code Repositories for REST API Docs；