利用ShowDoc自动生成api接口文档
最近在做新项目,感觉写完一个接口 还要去再写一遍api文档 挺浪费时间的,所以借用ShowDoc的api开放功能 自动生成api文档。
首先 去 https://www.showdoc.cc/ 注册一个账户,新建一个项目,
建立新项目后,选择该项目,打开,进入项目界面
然后点击项目,下拉选择项目设置,
可以看到开放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文档。
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。不要在URL中使用&符号来传递参数。传递参数请写在参数表格中 |
@param |
参数表格说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。 |
@json_param |
可选。当请求参数是json的时候,可增加此标签。请把json内容压缩在同一行内。 |
@return |
返回内容。请把返回内容压缩在同一行内。如果是json,程序会自动进行格式化展示。 如果是非json内容,则原样展示。 |
@return_param |
返回参数的表格说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。 |
@remark |
备注信息 |
@number |
可选。文档的序号。 |
利用ShowDoc自动生成api接口文档的更多相关文章
- SpringBoot + Swagger2 自动生成API接口文档
spring-boot作为当前最为流行的Java web开发脚手架,相信越来越多的开发者会使用其来构建企业级的RESTFul API接口.这些接口不但会服务于传统的web端(b/s),也会服务于移动端 ...
- Spring MVC学习总结(9)——Spring MVC整合swagger自动生成api接口文档
Swagger 号称:世界最流行的API框架,官网:http://swagger.io/,Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总 ...
- spring boot使用swagger生成api接口文档
前言 在之前的文章中,使用mybatis-plus生成了对应的包,在此基础上,我们针对项目的api接口,添加swagger配置和注解,生成swagger接口文档 具体可以查看本站spring boot ...
- 插件式WebApi服务及自动生成Api帮助文档
上一篇博客中,讲到了将WebApi Host到控制台和IIS,本篇总结一下如何将WebApi的Service以插件的形式进行动态部署,并设置Hoster的首页显示Api帮助文档,当然,也包括动态部署进 ...
- Spring Boot2配置Swagger2生成API接口文档
一.Swagger2介绍 前后端分离开发模式中,api文档是最好的沟通方式. Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务. 及时性 (接 ...
- 如何利用showdoc自动生成API文档
介绍 showdoc是一个适合IT团队的文档工具,阅读本文前需要对showdoc有基本了解 .基本介绍可看:https://www.showdoc.cc/help 对于写API文档这件事,虽然说文本编 ...
- 使用ShowDoc在线管理API接口文档
ShowDoc是什么 每当接手一个他人开发好的模块或者项目,看着那些没有写注释的代码,我们都无比抓狂.文档呢?!文档呢?!Show me the doc !! ShowDoc就是一个非常适合IT团队的 ...
- .netcore Swagger 生成 api接口文档
1, 引用第三方包, Swashbuckle.AspNetCore Swashbuckle.AspNetCore.Swagger Swashbuckle.AspNetCore.SwaggerUI 最简 ...
- Api接口文档管理工具,你知道哪些呢?
上周看到有人在我的Github开源项目中提了个issue,说是否考虑接入swagger.那今天我就用swagger与其他接口文档工具做对比,同时说说Api接口文档工具的那点事.如今,在前后端分离开发的 ...
随机推荐
- Mybatis-plus的使用
接口mapper需要继承BaseMapper<要操作的类>外加@Mapper mport org.apache.ibatis.annotations.Mapper; import org. ...
- 【实践总结】给Centos和Ubuntu设置静态网络IP以及配置ssh功能
作为一名以Windows平台为主的开发者,在接触和使用Linux系统的过程中总会遇到一系列的问题.每当这时候,我相信大部分人是和我一样的处理办法,就是网上各种搜索尝试直到问题解决为止,而有些问题,前后 ...
- Python笔记_类
1.类 1.1 类的定义 # 类的定义 class 类名: pass # pass是空语句,不具有任何意义,仅为了保持程序结构完整性 # 创建对象 对象名 = 类名() 1.2 成员变量 # 成员变量 ...
- Java网络编程之InetAddress浅析
Java网络编程之InetAddress浅析 一.InetAddress综述 IP地址是IP使用的32位(IPv4)或者128位(IPv6)位无符号数字,它是传输层协议TCP,UDP的基础.InetA ...
- Android自动化测试探索(五)代码覆盖率统计
Android 代码覆盖率统计 本周开始准备统计Android自动化用例的代码覆盖率,将最终使用的方法记录下来. 覆盖率监测的原理 覆盖率监测的原理跟iOS上的原理差不多,大致的思路参考下吧, iOS ...
- jquery zTree插件 json 数据详解
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/ ...
- PyTorch : torch.nn.xxx 和 torch.nn.functional.xxx
PyTorch : torch.nn.xxx 和 torch.nn.functional.xxx 在写 PyTorch 代码时,我们会发现一些功能重复的操作,比如卷积.激活.池化等操作.这些操作分别可 ...
- 洛谷P1169 [ZJOI2007]棋盘制作 悬线法 动态规划
P1169 [ZJOI2007]棋盘制作 (逼着自己做DP 题意: 给定一个包含0,1的矩阵,求出一个面积最大的正方形矩阵和长方形矩阵,要求矩阵中相邻两个的值不同. 思路: 悬线法. 用途: 解决给定 ...
- codeforces 811 E. Vladik and Entertaining Flags(线段树+并查集)
题目链接:http://codeforces.com/contest/811/problem/E 题意:给定一个行数为10 列数10w的矩阵,每个方块是一个整数, 给定l和r 求范围内的联通块数量 所 ...
- Two Graphs 牛客网暑期ACM多校训练营(第一场)D 图论基础知识 全排列
链接:https://www.nowcoder.com/acm/contest/139/D来源:牛客网 Two undirected simple graphs and where are isomo ...