利用ShowDoc自动生成api接口文档

时间：2023-02-15 00:27:54

最近在做新项目，感觉写完一个接口 还要去再写一遍api文档 挺浪费时间的，所以借用ShowDoc的api开放功能 自动生成api文档。

首先 去 https://www.showdoc.cc/ 注册一个账户，新建一个项目，

利用ShowDoc自动生成api接口文档

建立新项目后，选择该项目，打开，进入项目界面

利用ShowDoc自动生成api接口文档

然后点击项目，下拉选择项目设置，

利用ShowDoc自动生成api接口文档

可以看到开放API，下面还有Api文档，数据字典文档

Windows系统安装步骤：

自动化生成API文档，首先需要下载Git ，推荐下载地址： 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/index.php?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/index.php?s=/api/open/fromComments ，其中，别忘记了url里含server目录。

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

  1. chmod +x showdoc_api.sh
  2. ./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/

语法说明

一个标准语法例子：

  1. /**
  2. * showdoc
  3. * @catalog 测试文档/用户相关
  4. * @title 用户登录
  5. * @description 用户登录的接口
  6. * @method get
  7. * @url https://www.showdoc.cc/home/user/login
  8. * @param username 必选 string 用户名
  9. * @param password 必选 string 密码
  10. * @param name 可选 string 用户昵称
  11. * @return {"error_code":0,"data":{"uid":"1","username":"12154545","name":"吴系挂","groupid":2,"reg_time":"1436864169","last_login_time":"0"}}
  12. * @return_param groupid int 用户组id
  13. * @return_param name string 用户昵称
  14. * @remark 这里是备注信息
  15. * @number 99
  16. */
关键字 说明
@catalog 生成文档要放到哪个目录。如果只是二级目录，则直接写目录名字。如果是三级目录，而需要写二级目录/三级目录，即用/隔开。如”一层/二层/三层”
@title 表示生成的文档标题
@description 是文档内容中对接口的描述信息
@method 接口请求方式。一般是get或者post
@url 接口URL。不要在URL中使用&符号来传递参数。传递参数请写在参数表格中
@param 参数表格说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。
@json_param 可选。当请求参数是json的时候，可增加此标签。请把json内容压缩在同一行内。
@return 返回内容。请把返回内容压缩在同一行内。如果是json，程序会自动进行格式化展示。 如果是非json内容，则原样展示。
@return_param 返回参数的表格说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。
@remark 备注信息
@number 可选。文档的序号。

相关文章