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地址}