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

董洪蒙

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

關(guān)鍵詞：ShowDoc，程序文檔

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

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

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

一、自行構(gòu)建API文檔本地服務(wù)器。

本人使用CentOS 7.8 64位系統(tǒng)，在本地利用虛擬化平臺布署，因為ShowDoc使用Docker技術(shù)，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相關(guān)環(huán)境，經(jīng)過漫長時間后，ShowDoc即布署完成。在內(nèi)網(wǎng)即可直接訪問，假定ShowDoc安裝的IP是10.0.0.100：

http：//10.0.0.100/web/#/

設(shè)置Docker自動啟動ShowDoc：

systemctl enable docker

docker update --restart=always showdoc

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

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

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

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，根據(jù)自己項目的具體配置，修改api key和url，即可使showdoc_api與項目專屬文檔形成關(guān)聯(lián)。在程序編寫時，可以在代碼起始處、或每個關(guān)鍵函數(shù)起始處添加如下注釋：

‘

/**

* showdoc

* @catalog 測試文檔/用戶相關(guān)

* @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，即可自動生成規(guī)整的API文檔，這極大便利于程序文檔的編寫，團隊開發(fā)人員只要形成了約定，在每段關(guān)鍵的API調(diào)用函數(shù)前，使用一些必要的注釋，即可生成規(guī)范的文檔，供后端和前端開發(fā)人員共享使用，大大提高了開發(fā)效率，方便了團隊開發(fā)的規(guī)范形成。