隨時發佈：REST API文檔的代碼倉庫中的持續集成與協做

本文主要內容：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的示例測試

您能夠測試文檔源文件的質量以及是否構建。您還能夠檢查拼寫或語法，但也能夠經過人爲進行檢查。但測試文檔的目的是減輕人類審閱者的審查負擔，自動化能節省時間，以即可以編寫，發佈和發佈更多文檔文件。

1.連接檢查

對於許多靜態站點生成器，有專門用於檢查站點中全部連接的庫。例如，在檢查像docslikecode.com這樣的Jekyll網站上的連接時，Travis CI工做很簡單：

#!/usr/bin/env bash
set -e # halt script on error
bundle exec jekyll build
bundle exec htmlproofer ./_site

經過這種類型的測試，人工審閱者沒必要花時間點擊新補丁中的每一個連接。若是須要更新外部連接，那麼這個測試的結果會通知您。若是內部連接因修補程序自己而中斷，則系統能夠在人爲查看修補程序以前修復它。

2.JSON格式

使用REST API文檔，請求和響應一般是JSON文件，對於閱讀文檔的人在將本身的環境與文檔進行比較時很是有價值。在讀者須要複製和粘貼請求的狀況下，正確格式化示例相當重要。在OpenStack中，咱們有一組包含JSON測試器和格式化程序的通用文檔工具。經過對傳入的修補程序對文檔文件運行此測試，讀者能夠肯定所包含的JSON文件是否格式正確。此外，當它們能夠在本地運行簡單命令以確保JSON格式正確時，它可使貢獻者更容易建立補丁。

3.驗證的請求和響應

高級文檔測試能夠檢查文檔中包含的示例請求和響應。用查看代碼文件相同的方式查看文檔文件時，準確性一般是最高值。所以，經過針對正常工做的API端點測試示例，您能夠證實這些示例也適用於實際狀況。這種類型的驗證提供了每次均可用的成功文檔示例，由於只有它們經過驗證測試，它們才被髮布。

4.創建檢查

自動化文檔測試能夠節省讀者的時間，由於他們沒必要本身構建文檔來查看輸出。此外您能夠測試損壞的連接或不正確格式化的JSON文件的構建。對於任何奇怪的問題，查看源文檔和輸出文檔都頗有幫助。

自動化測試功能除了能減小開發的時間以外，自動化測試還有助於進行項目流程測試，最近由於一直在使用EOLINKER進行API研發管理，所以推薦自動化測試功能，由於它支持UI模式和高級模式，能夠實現不一樣類型的自動化測試項目，好比登陸驗證就能夠用UI模式，高級模式則用來測試較爲複雜的項目，對比以前效率高了很多，對API自動化測試等方面有興趣的小夥伴前往瞭解下哦！ https://www.eolinker.com

 

結論

在與代碼庫相同的倉庫中協同處理文檔，能夠更好地爲客戶提供服務，不管他們是組織的內部仍是外部。經過將API文檔視爲代碼，您能夠找到自動化途徑，提升效率，加快文檔構建，在文檔中構建成功示例。