springboot整合swagger2

使用swagger2之前都是用Doclever管理的，后来实在忍不住繁琐的维护工作，动手整合了一个

虽然swagger3都有了，但是没找到怎么升级

swagger3介绍

---

1、Swagger2优点

整合到Spring Boot中，构建强大RESTful API文档。省去接口文档管理工作，修改代码，自动更新，Swagger2也提供了强大的页面测试功能来调试RESTful API。

2、Swagger2常用注解

Api：修饰整个类，描述Controller的作用
ApiOperation：描述一个类的一个方法，或者说一个接口
ApiParam：单个参数描述
ApiModel：用对象来接收参数
ApiProperty：用对象接收参数时，描述对象的一个字段
ApiResponse：HTTP响应其中1个描述
ApiResponses：HTTP响应整体描述
ApiIgnore：使用该注解忽略这个API
ApiError ：发生错误返回的信息
ApiImplicitParam：一个请求参数
ApiImplicitParams：多个请求参数

3、整合

加入pom

        
            io.springfox
            springfox-swagger2
            2.9.2
        
        
            io.springfox
            springfox-swagger-ui
            2.9.2
        

配置类

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yz.zhcz.controller.api"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot利用Swagger构建API文档")
                .description("接口文档")
                .version("version 1.0")
                .build();
    }
}

启动类注解

@EnableSwagger2
@SpringBootApplication
@MapperScan("com.yz.zhcz.mapper")
public class ZhczApplication {

    public static void main(String[] args) {
        SpringApplication.run(ZhczApplication.class, args);
    }

}

启动成功访问http://localhost/swagger-ui.html

 所有接口均显示在列，如果不想暴露指定接口可以加@ApiIgnore注解

这里有一点需要注意

如果你使用的是@RequestMapping

swagger会将Post、Get、Put、Delete等全部显示出来

单击接口展开单个接口的详细信息

点击Try it out 

 输入请求参数后点击Execute可发起请求

 

---

2020.4.10

续记：

默认的页面时spring-fox的UI，实体类字段多了简直难受，后来尝试下bootstrap的UI，具体哪个好用大家细品

首先替换掉springfox-swagger-ui依赖

        
            io.springfox
            springfox-swagger2
            2.9.2
        





        
            com.github.xiaoymin
            swagger-bootstrap-ui
            1.9.0
        

 接着在 @EnableSwagger2 下增加 @EnableSwaggerBootstrapUI

 

bootstrap UI：

---

踩坑 

一、字段注释未正常显示

问题：实体类增加注解后页面不显示

/**
 * 父级id
 */
@ApiModelProperty(value = "数据id",example = "1")
private Integer pId;

 解决方法：(尽量避免"p_id"这种命名方式，在swagger2文档页面有时会显示为"Pid"，这样就出现了显示错误)

二、控制台报类型转换错误：java.lang.NumberFormatException: For input string: ""

原因：在AbstractSerializableParameter的getExample方法中会将数值属性的example的转换数值类返回，example的默认值是""，因此当example没有赋值时，会出现下面的异常

11:33:31.184 [http-nio-80-exec-8] WARN  i.s.m.p.AbstractSerializableParameter - [getExample,421] - Illegal DefaultValue null for parameter type integer
java.lang.NumberFormatException: For input string: ""
	at java.base/java.lang.NumberFormatException.forInputString(NumberFormatException.java:68)
	at java.base/java.lang.Long.parseLong(Long.java:709)
	at java.base/java.lang.Long.valueOf(Long.java:1151)

解决方法：

（两种任选其一）

1.Integer类型字段增加默认值：example="1"

2.pom新增

        
        
        
            io.swagger
            swagger-annotations
            1.5.21
        
        
            io.swagger
            swagger-models
            1.5.21
        
        

        
        
            io.springfox
            springfox-swagger2
            2.9.2
        





        
            com.github.xiaoymin
            swagger-bootstrap-ui
            1.9.0