如何利用 showdoc 自动生成 API 文档

介绍

showdoc 是一个适合 IT 团队的文档工具，阅读本文前需要对 showdoc 有基本了解。基本介绍可看： https://www.showdoc.cc/help

对于写 API 文档这件事，虽然说文本编辑软件或者接口管理软件能在某种程度上提高我们的效率，但我们依然可以试图借助技术的力量，更自动化地生成 API 文档，释放自己的生产力。为此，showdoc 官方提供了一种自动化解决方案。在代码里编写特定格式的程序注释，然后 showdoc 通过读取这些注释来自动生成文档。由于这种方式不跟特定的语言耦合，因此它的使用范围相当广泛，可用支持 c++、java、php、node、python 等等常见的主流语言。采用这种方式，尽管我们在第一次填写注释的时候可能会有些繁琐，但是它后期带来的可维护性是非常高的。代码变动后，不需要再额外登录 showdoc，直接在代码里修改注释即可。同时自动化的脚本也可以加入持续集成或者某些自动化工程里，让“写 API 文档”这件事如"单元测试"般纳入工程工作流里面。

windows 下使用指引

windows 无法直接运行 sh 脚本，需要额外下载软件。推荐下载 git for windows：https://git-scm.com/download/win 下载后直接双击安装即可。如果从官网下载比较慢，可用考虑下载由第三方开发者维护的国内版(showdoc 官方不保证其长期稳定)： https://npm.taobao.org/mirrors/git-for-windows/v2.17.0.windows.1/Git-2.17.0-64-bit.exe

以上软件是基础环境。安装好了后，还需要下载 showdoc 官方脚本：https://www.showdoc.cc/script/showdoc_api.sh 下载后，将 showdoc_api.sh 放在你的项目目录下。右击，选择编辑。脚本内容的前面有两个变量，api_key 和 api_token，这个需要用户自行填写。关于这两个变量的取值，请登录 showdoc，进入某个项目的设置，点击开放 API，便可以看到说明。showdoc_api.sh 生成的文档会放进你填写的这个项目里。除了 api_key 和 api_token，还有一个 url 变量。如果是使用 www.showdoc.cc ，则不需要修改。如果是使用开源版 showdoc，则需要将地址改为http://xx.com/server/?s=/api/open/fromComments 其中，别忘记了 url 里含 server 目录。填写完毕，保存。然后直接双击运行，脚本会自动递归扫描本目录和子目录的所有文本代码文件，并生成 API 文档。为了方便测试，官方还提供了一个例子。请下载： https://www.showdoc.cc/script/api_demo.test 下载后，把 api_demo.test 文件放在 showdoc_api.sh 所在的目录或者子目录下。运行的时候它便会生成文档到你指定的项目地址中。如果你想参考官方 demo 是怎么写的，可用鼠标右击 api_demo.test，选择编辑。仿照此种写法，在你的项目中插入类似的注释，也能达到自动生成文档的效果。详细语法会在文章后面部分说明。

如果你想应用到其他项目，可以把 showdoc_api.sh 复制一份到其他项目中。使用方法和前面一样。

Linux/Mac 下使用指引

先 cd 进入你的项目目录，命令行模式下输入：

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

下载完毕，编辑

vi showdoc_api.sh

脚本内容的前面有两个变量，api_key 和 api_token，这个需要用户自行填写。关于这两个变量的取值，请登录 showdoc，进入某个项目的设置，点击开放 API，便可以看到说明。showdoc_api.sh 生成的文档会放进你填写的这个项目里。除了 api_key 和 api_token，还有一个 url 变量。如果是使用 www.showdoc.cc ，则不需要修改。如果是使用开源版 showdoc，则需要将地址改为 http://xx.com/server/?s=/api/open/fromComments，其中，别忘记了 url 里含 server 目录。

保存文件后。执行以下命令，脚本会自动递归扫描本目录和子目录的所有文本代码文件，并生成 API 文档。

 chmod +x showdoc_api.sh
./showdoc_api.sh

为了方便测试，官方还提供了一个例子。请下载： wget https://www.showdoc.cc/script/api_demo.test

下载后，把 api_demo.test 文件放在 showdoc_api.sh 所在的目录或者子目录下。运行的时候它便会生成文档到你指定的项目地址中。如果你想参考官方 demo 是怎么写的，可用 vi 命令打开 api_demo.test。仿照此种写法，在你的项目中插入类似的注释，也能达到自动生成文档的效果。详细语法会在文章后面部分说明。

如果你还想应用到其他项目，可以把 showdoc_api.sh 复制一份到其他项目中。使用方法和前面一样。或者不转移位置，直接通过参数指定扫描目录。如

./showdoc_api.sh /myapp/demo/

语法说明

一个标准语法例子：

	/**
	* showdoc
	* @catalog 测试文档 /用户相关
	* @title 用户登录
	* @description 用户登录的接口
	* @method get
	* @url https://www.showdoc.cc/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
	*/

语法说明


@catalog // 生成文档要放到哪个目录。如果只是二级目录，则直接写目录名字。如果是三级目录，而需要写二级目录 /三级目录，即用 / 隔开。  
@title   //表示生成的文档标题 
@description // 是文档内容中对接口的描述信息  
@method  //接口请求方式。一般是 get 或者 post 
@url  //接口 URL  
@param //参数表格说明。一行注释对应着表格的一行。用空格或者 tab 符号来隔开每一列信息。  
@return  //返回内容。请把返回内容压缩在同一行内。如果是 json，程序会自动进行格式化展示。 如果是非 json 内容，则原样展示。
@return_param //返回参数的表格说明。一行注释对应着表格的一行。用空格或者 tab 符号来隔开每一列信息。
@remark  //备注信息 
@number   //可选。文档的序号。

其他信息

请严格按照我们的语法来填写程序注释。如果格式不对，则可能引发未知的解析错误。

出于数据安全考虑，showdoc 不允许直接通过代码删除文档。只能新增或者修改。所以，如果你要删除文档，请登录 showdoc 网页端完成。

本脚本只能通过特定的程序注释来生成文档，使用范围有限。如果你是想通过其他方式自由地生成文档，如通过 word、通过博客软件等，请参考我们更自由的开放 API： https://www.showdoc.cc/page/102098

如果你的项目下太多文件，则可能导致脚本扫描很慢。推荐把脚本放到需要生成注释的那个目录里。一般来讲，一个项目不会所有目录都需要生成文档的