SpringBoot整合Swagger2

一：相关技术

1. Maven 项目管理工具

2. SpringBoot 2.6.3

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

二：代码展示

1. pom.xml  依赖

        <!-- springfox-boot-starter -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

        <!-- springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0</version>
            <exclusions>
                <exclusion>
                    <artifactId>swagger-annotations</artifactId>
                    <groupId>io.swagger</groupId>
                </exclusion>
                <exclusion>
                    <artifactId>swagger-models</artifactId>
                    <groupId>io.swagger</groupId>
                </exclusion>
            </exclusions>
        </dependency>
        <!-- springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>

        <!-- swagger-annotations -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.22</version>
        </dependency>
        <!-- swagger-models -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>

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","3211285379@qq.com"))
                .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<SysDept> 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依赖

        <!-- springfox-boot-starter -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

注意：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排除依赖。如下：

        <!-- springfox-swagger2 排除依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0</version>
            <exclusions>
                <exclusion>
                    <artifactId>swagger-annotations</artifactId>
                    <groupId>io.swagger</groupId>
                </exclusion>
                <exclusion>
                    <artifactId>swagger-models</artifactId>
                    <groupId>io.swagger</groupId>
                </exclusion>
            </exclusions>
        </dependency>

        <!-- 添加以下两个依赖 -->

        <!-- swagger-annotations -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.22</version>
        </dependency>
        <!-- swagger-models -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>