SpringBoot整合Swagger2

一：相关技术

1. Maven 项目管理工具

2. SpringBoot 2.6.3

3. Swagger2 3.0.0 接口文档生成工具

二：代码展示

1. pom.xml  依赖

        
        
            io.springfox
            springfox-boot-starter
            3.0.0
        

        
        
            io.springfox
            springfox-swagger2
            3.0.0
            
                
                    swagger-annotations
                    io.swagger
                
                
                    swagger-models
                    io.swagger
                
            
        
        
        
            io.springfox
            springfox-swagger-ui
            3.0.0
        

        
        
            io.swagger
            swagger-annotations
            1.5.22
        
        
        
            io.swagger
            swagger-models
            1.5.22
        

2. SwaggerConfig.java  Swagger配置类

@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.system.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo getApiInfo(){
        return new ApiInfoBuilder()
                .title("若依后台管理平台") // 文档标题
                .description("若依后台管理平台的文档描述") // 文档描述
                .termsOfServiceUrl("https://www.baidu.com/")
                .contact(new Contact("w","https://blog.csdn.net/weixin_48568302","[email protected]"))
                .version("1.0")
                .build();

    }
}

3. SysDeptController.java  controller 使用案例

@RestController
@RequestMapping("/system/dept")
@Api(tags = "部门表接口")
public class SysDeptController {

    /**
     * 部门表业务层
     */
    @Resource
    private SysDeptServiceI sysDeptService;

    /**
     * 分页查询部门表
     * @param sysDept
     * @return
     */
    @GetMapping("/list")
    @ApiOperation("查询部门表")
    public AjaxResult findByPage(SysDept sysDept){
        List sysDeptList = sysDeptService.findByCondition(sysDept);
        return AjaxResult.success(sysDeptList);
    }

    /**
     * 按主键查询部门表
     * @param deptId
     * @return
     */
    @GetMapping("/{deptId}")
    @ApiOperation("按主键查询部门表")
    public AjaxResult getById(@ApiParam("主键") @PathVariable Serializable deptId){
        return AjaxResult.success(sysDeptService.getById(deptId));
    }

    /**
     * 增加部门表
     * @param sysDept
     * @return
     */
    @PostMapping
    @ApiOperation("增加部门表")
    public AjaxResult add(@RequestBody SysDept sysDept){
        sysDeptService.save(sysDept);
        return AjaxResult.success();
    }

    /**
     * 修改部门表
     * @param sysDept
     * @return
     */
    @PutMapping
    @ApiOperation("修改部门表")
    public AjaxResult edit(@RequestBody SysDept sysDept){
        sysDeptService.updateById(sysDept);
        return AjaxResult.success();
    }

    /**
     * 按主键删除部门表
     * @param deptId
     * @return
     */
    @DeleteMapping("/{deptId}")
    @ApiOperation("按主键删除部门表")
    public AjaxResult removeById(@ApiParam("主键") @PathVariable Serializable deptId){
        sysDeptService.removeById(deptId);
        return AjaxResult.success();
    }
}

4. 访问接口文档

http://localhost:8080/swagger-ui/index.html

 

三：问题与解决

1. Swagger2 3.0.0 版本访问页面失败问题

解决方法：

        添加springfox-boot-starter依赖

        
        
            io.springfox
            springfox-boot-starter
            3.0.0
        

注意：Swagger2 3.0.0之前版本不需要springfox-boot-starter依赖

2. Illegal DefaultValue null for parameter type integer

java.lang.NumberFormatException: For input string: ""

2.1 报错信息，如下：

2.2 报错原因，如下：

进入到报错信息中，swagger包下对应的抽象类的方法AbstractSerializableParameter.getExample()

 原因：缺少对空串的判断。

2.3 解决方案

方案一：

        将源码下载下来，修改判断方法为if(this.example == null || "".equals(this.example))，打成jar包在使用。

方案二：

        增加依赖，exclusions排除依赖。如下：

        
        
            io.springfox
            springfox-swagger2
            3.0.0
            
                
                    swagger-annotations
                    io.swagger
                
                
                    swagger-models
                    io.swagger
                
            
        

        

        
        
            io.swagger
            swagger-annotations
            1.5.22
        
        
        
            io.swagger
            swagger-models
            1.5.22