swagger-ui快速入门教程
title: swagger ui快速入门教程
catalog: true
date: 2019-10-31 15:30:54
subtitle: 通过使用易水公共组件快速开启和关闭swagger ui,生成软件接口说明文档
header-img: http://static.yishuifengxiao.com/blog/global/backgroup/article.jpg
tags:
- spring security
- 易水组件
catagories: - spring security
快速启动
1 引入相关依赖
<dependency>
<groupId>com.yishuifengxiao.common</groupId>
<artifactId>common-spring-boot-starter</artifactId>
<version>4.1.2</version>
</dependency>
2 开启配置
在配置文件中加入以下配置即可快速开启 swagger-ui 功能。
yishuifengxiao.swagger.base-package= 需要扫描的控制器代码的路径
加入上述配置后即可通过 http://ip:port/doc.html 查看 swagger-ui 增强文档。
也可以通过 http://ip:port/swagger-ui.html 查看 swagger-ui 原生文档。
此外,也可以通过http://ip:port/v2/api-docs查看元数据
这里只是简化了 swagger-ui 的扫描注解,对于软件开发过程中必须 swagger-ui 其他 API 注解仍然不可省略。
下面是一个简单的 swagger-ui 配置文档示例
@Api(value = "【测试接口】测试接口", tags = {"测试接口"})
@Valid
@Controller
@RequestMapping
@Slf4j
public class WebConftroller {
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "登录的用户名"),
@ApiImplicitParam(name = "loginIp", value = "登录ip"),
@ApiImplicitParam(name = "pass", value = "登录结果,true表示成功,false失败"),
@ApiImplicitParam(name = "pageSize", value = "分页大小,分页的大小不能小于1,默认值为20"),
@ApiImplicitParam(name = "pageNum", value = "当前页的页码,页码的大小不能小于1,默认值为1")})
@ApiOperation(value = "分页查询登录记录", notes = "分页查询登录记录")
@GetMapping("/demo")
@ResponseBody
public Response<String> findPage(
HttpServletRequest request, HttpServletResponse response,
@RequestParam(value = "username", required = false) String username,
@RequestParam(value = "loginIp", required = false) String loginIp,
@RequestParam(value = "pass", required = false) Boolean pass,
@RequestParam(name = "pageSize", defaultValue = "20", required = false) Integer pageSize,
@RequestParam(name = "pageNum", defaultValue = "1", required = false) Integer pageNum) {
return Response.suc();
}
}
特别鸣谢:
此项功能中的 doc.html 界面中功能使用到了刀哥的 swagger-bootstrap-ui 中的功能 ,在此特别感谢 刀哥 的大力支持,关于 swagger-bootstrap-ui 的详细说明请参见刀哥的 swagger-bootstrap-ui 文档
配置参数
# swagger-ui文档的标题
yishuifengxiao.swagger.title=API接口文档
# swagger-ui文档描述
yishuifengxiao.swagger.description=易水风萧 接口说明文档
#swagger-ui 项目服务的url
yishuifengxiao.swagger.terms-of-service-url=http://www.yishuifengxiao.com/
# swagger-ui 文档分组的名字
yishuifengxiao.swagger.group-name=default
# swagger-ui 文档版本
yishuifengxiao.swagger.version=1.0.0
# 项目联系人名字
yishuifengxiao.swagger.contact-user=yishuifengxiao
# 项目联系的url
yishuifengxiao.swagger.contact-url=http://www.yishuifengxiao.com/
# 项目联系邮箱
yishuifengxiao.swagger.contact-email=zhiyubujian@163.com
以上常规配置都有缺省默认值,用户在使用 易水风萧通用组件 时,如果没有特别需要,使用默认配置即可。
进阶配置
一般情况下,使用 swagger-ui 的常规配置即可满足日常开发需要,但是在某些情况下,可能需要一些高级配置。如,需要通过在所有的 API 接口上批量加上一个默认参数,此时即可用通用组件的高级配置功能了。
yishuifengxiao.swagger.contact.auths[0].name=Authorization
yishuifengxiao.swagger.contact.auths[0].description=自定义必填请求头
yishuifengxiao.swagger.contact.auths[0].modelRef=string
yishuifengxiao.swagger.contact.auths[0].parameterType=header
yishuifengxiao.swagger.contact.auths[0].required=false
上述示例配置在 API 文档中的所有请求中批量添加了一个参数名为 Authorization 的请求头参数。
yishuifengxiao.swagger.contact.auths 是一个数组,可以添加多个配置,更多详细配置可参见参见 swagger-ui 的 ParameterBuilder 用法配置
资源链接
易水公共组件官方文档地址:http://doc.yishuifengxiao.com
易水公共组件源码地址:https://gitee.com/zhiyubujian/common-starter
易水风萧个人博客 http://www.yishuifengxiao.com
相关博客
-
swagger ui快速入门教程
-
基于易水公共组件的全局异常捕获
-
基于易水公共组件的验证码快速入门教程
-
springboot整合单点登录sso
-
搭建基于易水公共组件的资源服务器
-
spring security之获取当前用户信息
-
基于易水公共组件的权限管理系统
CSDN-Ada助手: 非常感谢CSDN博主分享《风铃虫入门教程:快速创建风铃虫》这篇博客,我觉得你的文章非常详细,对于想要学习风铃虫的读者来说非常有帮助。下一篇博客你可以继续写关于风铃虫的进阶技巧,比如如何应用风铃虫进行数据爬取、如何解决反爬虫等问题,相信会吸引更多读者的关注。期待你的下一篇博客! 为了方便博主创作,提高生产力,CSDN上线了AI写作助手功能,就在创作编辑器右侧哦~(https://mp.csdn.net/edit?utm_source=blog_comment_recall )诚邀您来加入测评,到此(https://activity.csdn.net/creatActivity?id=10450&utm_source=blog_comment_recall)发布测评文章即可获得「话题勋章」,同时还有机会拿定制奖牌。
不要问我y: 请问楼主的表格是自己制作的吗?还是运行代码以后会有输出呀,我运行后肢体是没有报错,没有输出正常吗
new 杨海波: 感谢博主,弄了一晚上
yueding289a: 码住,求博主联系方式,我的微信xiaozhu0264,在线等回复
影月~: 这个问题昨天绊了我一天,感谢博主