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

[star7th]

介绍

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

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

[jaycee110905]

已经在用了

[star7th]

@jaycee110905 有遇到问题记得反馈下

[houshengzi]

好几年前已经在用了，原来你还在更新这项目

[star7th]

@houshengzi 这个项目出生差不多三年了。我有空就断断续续更新下

[zarte]

有空试试。

[juneszh]

希望批量管理更人性化些。最近做了一个复制项目的操作，然后有一半文档其实是不需要的，结果有个“非空文件夹不能删”的限制，需要一个个点开文档“叉”掉再删文件夹，花了半个钟。

另外还有一个 bug：文档设置了二级文件夹后，不能再设回一级文件夹（二级的下拉没有“空”选项）

[star7th]

@juneszh 批量管理功能其实是有在思考。包括批量添加 /删除项目成员到不同项目，批量删除文档。有空再更新吧。
至于不能设置回一级目录，这个 bug 好久之前修复了。去更新版本吧。

[chengfeng1992]

去年用了半年多 showdoc，体验还不错。
出逃是因为：每次更新版本就会有各种 bug、数据丢失、数据错乱等问题。

[star7th]

@chengfeng1992 每次更新都测试过的，不会导致数据丢失。建议你仔细阅读文档操作。showdoc 升级的方式不是覆盖代码那样的升级，而是先安装然后再迁入数据。

[cncqw]

没记错 showdoc 后端用的 thinkphp3.2，前端用 vue.js ，蜜汁组合，有时候想自己加个功能改个样式啥的都非常麻烦

[star7th]

@cncqw 用 thinkphp3.2 是历史原因，当时是为了兼容旧版 PHP 环境。如果上新框架如 Laravel，则增加了部署难度，需要在旧 linux 服务器上安装新 php 版本。showdoc 相当多的开发者不是 php 开发者，追新不是一件好事。
此外，php 作为纯后端，VUE 用作纯前端，前后端分离反而更容易开发。
如果你说的麻烦指的是使用 vue 导致每次修改前端都要打包，那么，我想说，这是前端工程化的潮流，以后都会往这个趋势走。

[LWXYFER]

文档只是注释生成，不会走 AST 获取其他数据对吧 ?

[star7th]

@LWXYFER 不会。下载这个脚本 wget https://www.showdoc.cc/script/showdoc_api.sh ，直接看它地源码就知道了。它只上传注释

[anxious]

请问相比于 doxygen 或者是 javadoc，这个的优势在哪里？

[star7th]

@anxious
1，showdoc 生成的文档美观很多 ，这是个 api 文档例子 https://www.showdoc.cc/web/#/demo?page_id=9
2，showdoc 不限定特定语言或者框架，可以支持多种语言。
3，showdoc 不仅可以自动生成文档，也支持到网页端编辑，团队协作

[dobelee]

现在不清楚怎么样了。两年前引入，发现 bug 特别多，包括权限、session、cookie、markdown，菜单列表都有很重的 bug。后来花了很多功夫做二开。

[madao2015]

表示一直在用，有空试试看

[star7th]

@dobelee 跟两年前差别还是挺多的。你有时间可以把 bug 都列出来，看是否解决了

[heybuddy]

如果可以的话，楼主是否可以考虑加个 webhook，这样可以很方便的在钉钉等支持 webhook 的聊天机器人提醒文档有更新

[star7th]

@heybuddy 关于更新提醒，其实我有考虑过。但是好像如果每一次修改都推送一次提醒（无论是用钉钉还是邮件提醒等方式），都太频繁了。比如说，我只是修改几个字，预览下，然后又再修改。所有我也不知道做更新提醒是不是一件好事

[heybuddy]

@star7th 我们公司在开发中用的是楼主你的 showdoc，实际开发中就碰到了前端和后端沟通不及时的问题

[star7th]

@heybuddy 那你们介意频繁被通知的情况吗

[zzf2017]

问下，为什么用了那个 git bash 测试那个 api_demo.test ,好像一闪而过，但是 showdoc 项目中也没有出现 东西啊 ？是我用的不对吗？ @star7th

[star7th]

@zzf2017 正常情况它会暂停的。你这样情况可能出现了异常。建议 右击菜单，选择“ GIT BASH Here"，在弹出的命令行窗口手动执行 sh showdoc_api.sh

[heybuddy]

我们是不介意的。

[heybuddy]

@star7th 我觉得可以在确定的地方加个复选框，默认选中使用 webhook，可以给用户有个选择。

[zqguo]

自动生成文档怎么搞？

[star7th]

@heybuddy 让其可选的话，是一个选择。后面考虑吧

[star7th]

@zqguo 原理是根据程序注释来生成。详细看文档吧

[fhefh]

很棒~~ 谢谢楼主~

https://github.com/star7th/showdoc

[chengfeng1992]

@star7th 我是用的 web 版本，不是自己安装的。应该在 17 年 2 月份开始用的。
出现过：
1. 文档目录丢失，但是在搜索中可以找到。
2. 文档直接丢失。
3. 个别符号乱码，在 html 转义字符上比较常见。 比如 & 变成了&
4. 文档长一点，比如超过一页 markdown，修改的时候特别卡。
5. 个别 markdown 支持不好。大约记得有一个类似是 ` MM 月 dd 日[周 F] ` 这样的，h5 显示直接就 bug 了。
6. 目录排序很混乱。比如序号都是 1，有时候按时间正序，有时候按倒序。不同项目还不同。
...

反正就是问题比较多，团队成员意见也都比较大，就换了其它的。

希望越来越好吧~

[star7th]

@chengfeng1992 你说的这些确实是问题。
第 1 和第 2 点是同一个问题。因为 showdoc 曾经很长一段存在一个不好发现的 bug ——当一个目录的父目录设置为自己或者一个二级目录转为三级目录的时候，会导致整个目录下的文档消失。数据库是有数据，但不会展示出来。现在已经修正问题了。
第 3 点，因为曾经调整过几次转义和安全的问题，所以调整过程中可能有用户的文档数据被转义了。确实是 showdoc 问题。现在已经兼顾好了安全和转义的问题。
第 4 点，这个问题现在还存在着，因为我觉得太长文档的情况不会多。看来我应该预先判断文档长度，来提示用户要不要关闭 html 预览。长文档特别卡的情况是因为 html 预览渲染太消耗浏览器性能。
第 5 点，showdoc 对 markdown 的转换有个改动，已经大部分支持标准语法。有没有解决极端情况下的语法，则尚不清除。
第 6 点，默认情况下，按照序号排序。当序号都相同的时候，将按 id 排序。不知道你说的问题还存在不存在。

[no13bus]

确实好用。我们一直在用

[zqguo]

@star7th 这里发现一个界面问题，进入后台管理，左侧栏有点没有对齐。

[star7th]

@zqguo 发现好像是差了一个像素。下个版本修正

[balabalaguguji]

编写有些麻烦，推荐你试下专业的 API 文档工具吧 https://easydoc.xyz