使用showdoc快速生成文档

如何使用showdoc快速生成文档

  • 1,下载git for windows
  • 2,下载showdoc官方脚本
  • 3,编辑showdoc_api.sh文件
  • 4,修改自己控制器中的注释
  • 5,生成文档

1,下载git for windows

1、地址: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

双击安装完成之后下一步

2,下载showdoc官方脚本

地址:https://www.showdoc.cc/script/showdoc_api.sh

下载完之后将showdoc_api.sh脚本文件放在自己项目中,这里我放在了我的控制器这一目录中。

3,编辑showdoc_api.sh文件

3、右击,编辑
脚本内容的前面有两个变量,api_key 和 api_token ,

这两个变量的取值,请登录showdoc,进入某个项目的设置,点击开放API,便可以看到。

注意:还有一个url变量。如果是使用www.showdoc.cc ,则不需要修改。如果是使用开源版showdoc,则需要将地址改为http://xx.com/server/index.php?s=/api/open/fromComments ,其中,别忘记了url里含server目录。

4,修改自己控制器中的注释

在自己的接口的注释中添加注释

/**
* 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
*/

每个注释的意义:

1.@catalog:生成文档要放到哪个目录。如果只是二级目录,则直接写目录名字。如果是三级目录,而需要写二级目录/三级目录,即用/隔开。如”一层/二层/三层”

2.@title:表示生成的文档标题

3.@description:是文档内容中对接口的描述信息

4.@method:接口请求方式。一般是get或者post

5.@url:接口URL

6@param:参数表格说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。

7.@return:返回内容。请把返回内容压缩在同一行内。如果是json,程序会自动进行格式化展示。 如果是非json内容,则原样展示。

8.@return_param:返回参数的表格说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。

9.@remark:备注信息

10.@number:可选。文档的序号。

5,生成文档

双击该脚本文件运行,脚本会自动递归扫描本目录和子目录的所有文本代码文件,并生成API文档。

至此相关接口的文档就生成了,感谢各位的阅读。如有不足之处请指正,谢谢。

官方文档地址:https://www.showdoc.cc/page/741656402509783

你可能感兴趣的:(学习)