董洪蒙

摘要：软件开发者一项重要的工作就是文档的编写，但这是一项枯燥泛味的工作，大多数软件开发者只专心于代码的编写，后期的文档不善于编写，造成团队开发的一些困扰。如果在程序代码开发阶段中就能实现文档的编写，无疑是一举两得的事情。本文探讨了如何使用国产优秀的开源软件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调用函数前，使用一些必要的注释，即可生成规范的文档，供后端和前端开发人员共享使用，大大提高了开发效率，方便了团队开发的规范形成。