springboot2 整合 swagger2
springboot整合三板斧
第一步、引入pom
<dependency> <groupid>com.spring4all</groupid> <artifactid>swagger-spring-boot-starter</artifactid> <version>1.9.0.release</version> </dependency> <dependency> <groupid>com.github.xiaoymin</groupid> <artifactid>swagger-bootstrap-ui</artifactid> <version>1.9.6</version> </dependency> <dependency> <groupid>io.swagger</groupid> <artifactid>swagger-annotations</artifactid> <version>1.5.22</version> </dependency> <dependency> <groupid>io.swagger</groupid> <artifactid>swagger-models</artifactid> <version>1.5.22</version> </dependency>
swagger-spring-boot-starter该项目主要利用spring boot的自动化配置特性来实现快速的将swagger2引入spring boot应用来生成api文档，简化原生使用swagger2的整合代码。
swagger-bootstrap-ui是springfox-swagger的增强ui实现，为java开发者在使用swagger的时候，能拥有一份简洁、强大的接口文档体验
swagger-annotations,swagger-models是因为springfox-swagger2包里有swagger-models-1.5.20.jar报错。所以替换成1.5.22版本
java.lang.numberformatexception: for input string: "" at java.lang.numberformatexception.forinputstring(numberformatexception.java:65) at java.lang.long.parselong(long.java:601) at java.lang.long.valueof(long.java:803) at io.swagger.models.parameters.abstractserializableparameter.getexample(abstractserializableparameter.java:412) at sun.reflect.nativemethodaccessorimpl.invoke0(native method) at sun.reflect.nativemethodaccessorimpl.invoke(nativemethodaccessorimpl.java:62) at......
看下1.5.20版本里abstractserializableparameter.java源码：
public object getexample() {
if (this.example == null) {
return null;
} else {
try {
if ("integer".equals(this.type)) {
return long.valueof(this.example);
}
if ("number".equals(this.type)) {
return double.valueof(this.example);
}
if ("boolean".equals(this.type) && ("true".equalsignorecase(this.example) || "false".equalsignorecase(this.defaultvalue))) {
return boolean.valueof(this.example);
}
} catch (numberformatexception var2) {
logger.warn(string.format("illegal defaultvalue %s for parameter type %s", this.defaultvalue, this.type), var2);
}
return this.example;
}
}
这里只判断了this.example == null才返回null，其余会去进行转换，而空字符串也会进行转换，导致格式抛出格式化转换异常.再来看下1.5.22版本里abstractserializableparameter.java源码：
public object getexample() {
if (this.example != null && !this.example.isempty()) {
try {
if ("integer".equals(this.type)) {
return long.valueof(this.example);
}
if ("number".equals(this.type)) {
return double.valueof(this.example);
}
if ("boolean".equals(this.type) && ("true".equalsignorecase(this.example) || "false".equalsignorecase(this.defaultvalue))) {
return boolean.valueof(this.example);
}
} catch (numberformatexception var2) {
logger.warn(string.format("illegal defaultvalue %s for parameter type %s", this.defaultvalue, this.type), var2);
}
return this.example;
} else {
return this.example;
}
}
对example同时进行了null和空值的判断，官方也发现了自己的这个问题，我们进行相应的替换即可
第二部、配置
swagger-spring-boot-starter相关配置信息可参考如下地址:
- 源码地址
- github：
- 码云：
- 使用样例：
- 博客：
- 社区：
swagger-bootstrap-ui相关配置信息可参考如下地址:
官方地址：
swagger-bootstrap-ui目前已改名了knife4j-spring-boot-starter项目正式更名为knife4j,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端ui前端.
swagger-bootstrap-ui的所有特性都会集中在
knife4j-spring-ui包中,并且后续也会满足开发者更多的个性化需求.
swagger:
version: 1.0v # 版本号
authorization: # 全局参数
name: authorization # 鉴权策略id，对应 securityreferences id
type: apikey # 鉴权策略，可选 apikey | basicauth | none，默认apikey
key-name: x-token # 鉴权传递的header参数
# auth-regex: ^.*$ # 需要开启鉴权url的正则, 默认^.*$匹配所有url
ui-config: # 排序规则
operations-sorter: method # 按方法定义顺序排序
tags-sorter: alpha # 按字母表排序
docket: # 分组配置
common:
base-package: com.xxxx.a
description: api接口文档
title: xxx接口
contact:
name: xxx
url: https://cn.bing.com/
hq:
base-package: com.xxxx.b
description: api接口文档
title: xxx接口
contact:
name: xxx
url: https://zc.happyloves.cn:4443/wordpress/
shop:
base-package: com.xxxx.c
description: api接口文档
title: xxx接口
contact:
name: xxx
url: https://zc.happyloves.cn
第三步、注解
@enableswagger2doc // 启用swagger2
@enableswaggerbootstrapui //启用swagger-bootstrap-ui
@springbootapplication
public class webapplication {
public static void main(string[] args) {
springapplication.run(webapplication.class, args);
}
}
编写代码
@api(value = "demoone-demoone服务~~~~~~~~", tags = {"1-demoone-demoone服务"})
@slf4j
@validated
@restcontroller
@requestmapping("/common/demoone")
public class demoonecontroller {
private final demooneservice service;
@autowired
public demoonecontroller(demooneservice service) {
this.service = service;
}
//=====================================================================================delete=====================================================================================
@apioperation(value = "根据主键id删除", notes = "根据主键id删除~~~~~~~~~~~~~")
@deletemapping("/{id}")
public apimessage deletebyid(@pathvariable @min(1) int id) throws exception {
return service.deletebyid(id);
}
//=====================================================================================get========================================================================================
@apioperation(value = "获取所有数据", notes = "获取所有数据~~~~~~~~~~~~~")
@getmapping("/")
public apimessage<list<demooneresponse>> getalllist() {
return service.getalllist();
}
@apioperation(value = "根据主键id获取数据", notes = "根据主键id获取数据~~~~~~~~~~~~~")
@apiimplicitparams(value = {
@apiimplicitparam(name = "id", required = true, value = "主键id", paramtype = "path", datatype = "string"),
})
@getmapping("/{id}/{name}")
public apimessage<demooneresponse> getbyid(@pathvariable @min(1) int id, @pathvariable @assertfalse boolean name) {
return service.getbyid(id);
}
//=====================================================================================post=======================================================================================
@apioperation(value = "新增demoone数据", notes = "新增demoone数据~~~~~~~~~~~~~")
@postmapping("/")
public apimessage<demooneresponse> save(@requestbody @valid demoonerequest parameter) {
return service.adddemoone(parameter);
}
//=====================================================================================put========================================================================================
@apioperation(value = "更新demoone数据", notes = "更新demoone数据~~~~~~~~~~~~~")
@putmapping("/")
public apimessage<demooneresponse> update(@requestbody @valid demoonerequest parameter) {
return service.update(parameter);
}
大功告成！！！启动访问如下地址：
swagger2地址：
{ip地址}
