使用開源軟件自動生成API文檔

董洪蒙

摘要：軟件開發者一項重要的工作就是文檔的編寫，但這是一項枯燥泛味的工作，大多數軟件開發者只專心于代碼的編寫，后期的文檔不善于編寫，造成團隊開發的一些困擾。如果在程序代碼開發階段中就能實現文檔的編寫，無疑是一舉兩得的事情。本文探討了如何使用國產優秀的開源軟件ShowDoc自動通過程序代碼注釋進行文檔的自動生成，為前后端開發者提供了編寫文檔的捷徑，共同發展提高。

關鍵詞：ShowDoc，程序文檔

作為軟件開發者，文檔的編寫整理是一項十分重要的工作。開發人員都很希望別人能寫技術文檔，而自己卻很不希望要寫文檔。因為寫文檔需要花大量的時間去處理格式排版，想著新建的word文檔放在哪個目錄等各種非技術細節。word文檔零零散散地放在團隊不同人那里，需要文檔的人要花費大量時間進行溝通，通過QQ、郵箱接收對方的文檔。這種溝通方式當然可以，只是效率不高。

ShowDoc就是一個非常適合軟件開發團隊的在線文檔分享工具，它可以加快團隊之間溝通的效率，并且有著精巧的設計，可以通過程序編寫過程中十分便利地順手寫的程序注釋，自動形成規范的文檔，貼近于開發人員的使用習慣，是非常優秀的開源工具。

下面本人就自己在軟件開發工作中的ShowDoc使用經驗，及使用心得分享給大家：

一、自行構建API文檔本地服務器。

本人使用CentOS 7.8 64位系統，在本地利用虛擬化平臺布署，因為ShowDoc使用Docker技術，Docker需要container-selinux包，需要手工安裝，在https：//pkgs.org/download下載后，拖入linux后手工安裝：

cd /opt

yum localinstall -y container-selinux-2.119.2-1.911c772.el7_8.noarch.rpm

下面下載ShowDoc，由其自動安裝Docker容器：

wget https：//www.showdoc.com.cn/script/showdoc

chmod +x showdoc

./showdoc

由于要下載安裝Docker相關環境，經過漫長時間后，ShowDoc即布署完成。在內網即可直接訪問，假定ShowDoc安裝的IP是10.0.0.100：

http：//10.0.0.100/web/#/

設置Docker自動啟動ShowDoc：

systemctl enable docker

docker update --restart=always showdoc

二、使用ShowDoc手工、自動編寫、添加文檔

使用ShowDoc默認密碼登錄后，在頁面上新建文檔，即可進入某個項目的詳細文檔編輯頁面，類似于Markdown的編輯頁面，手工編輯一些說明、全局錯誤碼、修改記錄等全局性的API文檔，可以非常方便地便于后端、前端的開發人員翻閱。

手工編寫不是開發人員的常規選擇，更直接、便利的方式是通過代碼中常規注釋來自動生成文檔，貼近于后端開發人員的開發習慣，是值得推薦的方式：

wget https：//www.showdoc.cc/script/showdoc_api.sh

chmod a+x showdoc_api.sh

wget https：//www.showdoc.cc/script/api_demo.test

api_demo.test是一個示例性的文檔，從中可以拿到完整的注釋參考。編輯showdoc_api.sh，根據自己項目的具體配置，修改api key和url，即可使showdoc_api與項目專屬文檔形成關聯。在程序編寫時，可以在代碼起始處、或每個關鍵函數起始處添加如下注釋：

‘

/**

* showdoc

* @catalog 測試文檔/用戶相關

* @title 用戶注冊

* @description 用戶注冊的接口

* @method post

* @url https：//www.showdoc.com.cn/home/user/login

* @param username 必選 string 用戶名

* @param password 必選 string 密碼

* @param name 可選 string 用戶昵稱

* @return {"error_code"：0，"data"：{"uid"："1"，"username"："12154545"，"name"："吳系掛

"，"groupid"：2，"reg_time"："1436864169"，"last_login_time"："0"}}

* @return_param groupid int 用戶組id

* @return_param name string 用戶昵稱

* @remark 這里是備注信息

* @number 99

*/

‘

我們可以與git配合，做成日志的自動更新，定時啟動showdoc_api.sh，即可自動生成規整的API文檔，這極大便利于程序文檔的編寫，團隊開發人員只要形成了約定，在每段關鍵的API調用函數前，使用一些必要的注釋，即可生成規范的文檔，供后端和前端開發人員共享使用，大大提高了開發效率，方便了團隊開發的規范形成。