showdoc 自动生成API文档

用了很久的showdoc 文档管理，今天又发现文档自动生成工具，这 … … 简直不要太舒服了。

下面我们说下怎么实现文档自动化生成吧。

windows下使用指引

第一步：

[注册 showdoc 账号](https://www.showdoc.cc/ "注册 showdoc 账号") / [搭建私有版 showdoc 项目。](https://www.php.cn/blog/detail/23593.html "搭建私有版 showdoc 项目。")

第二步：

创建新项目用于存储本次开发接口文档归类

第三步：

打开项目设置，找到项目文件夹 开放API 下的 api_key + api_token 稍晚点使用，这两个是很重要的哦 ~~

第四步：

windows 环境的小伙伴是需要下载一下 Git 的哈； 
git 环境，想必大家都比较熟悉了，不熟悉的小伙伴可能需要扩展一下自己的知识储备了。
推荐下载git for windows：https://git-scm.com/download/win 下载后直接双击安装即可。
如果从官网下载比较慢，可用考虑下载由第三方开发者维护的国内版 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 ，这个需要用户自行填写。（也就是上面 创建项目设置开放api中的两个参数）
还有一个url变量。如果是使用www.showdoc.cc ，则不需要修改。如果是使用 开源版 showdoc，则需要将地址改为http://xx.com/server/index.php?s=/api/open/fromComments ，其中，别忘记了url里含server目录。
填写完毕，保存。然后直接双击运行，脚本会自动递归扫描本目录和子目录的所有文本代码文件，并生成API文档。

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

下载后，把api_demo.test文件放在showdoc_api.sh所在的目录或者子目录下。运行的时候它便会生成文档到你指定的项目地址中。

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

Linux/Mac下使用指引

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

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

下载完毕，编辑

vi showdoc_api.sh

脚本内容的前面有两个变量，api_key 和 api_token ，这个需要用户自行填写。（同上不要忘记 url变量哈）

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

chmod +x showdoc_api.sh
./showdoc_api.sh

测试，可以使用官方还提供了一个例子。（测试方式同上）

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

语法说明

一个标准语法例子：

/**
* showdoc
* @catalog 测试文档/用户相关
* @title 用户登录
* @description 用户登录的接口
* @method get
* @url https://www.showdoc.cc/home/user/login
* @header token 可选 string 设备token 
* @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。不要在URL中使用&符号来传递参数。传递参数请写在参数表格中
@header	可选。header说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。
@param	参数表格说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。
@json_param	可选。当请求参数是json的时候，可增加此标签。请把json内容压缩在同一行内。
@return	返回内容。请把返回内容压缩在同一行内。如果是json，程序会自动进行格式化展示。如果是非json内容，则原样展示。
@return_param	返回参数的表格说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。
@remark	备注信息
@number	可选。文档的序号。