SpringBoot集成Swagger2

自己构建项目过程中想用下Swagger做接口文档管理，就记录下集成Swagger2过程

1、使用Swagger2先要添加依赖
 

        <!--版本-->
<swagger.version>2.9.2</swagger.version>
 
        <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>${swagger.version}</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>${swagger.version}</version>
            </dependency>

2、需要创建一个配置类：

我本地创建了一个SwaggerConfig.java

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Author cdc
 * @Description swagger配置类
 * @Date 2023/8/1815:57
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 通过 createRestApi函数来构建一个DocketBean
     * 函数名,可以随意命名,喜欢什么命名就什么命名
     */

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())//调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容

                .select()

                //控制暴露出去的路径下的实例

                //如果某个接口不想暴露,可以使用以下注解

                //@ApiIgnore 这样,该接口就不会暴露在 swagger2 的页面下

                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))

                .paths(PathSelectors.any())

                .build();

    }

    //构建 api文档的详细信息函数

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

                //页面标题

                .title("Spring Boot Swagger2 构建RESTful API")

                //条款地址

                .termsOfServiceUrl("http://cdc.test.com/")

                .version("1.0")

                //描述

                .description("API 描述")

                .build();

    }
}

3、在需要引入Swagger的SpringBoot项目的application.yml加上Swagger配置，同时创建好对应的Controller类

swagger:
  enable: true

我本地创建了一个SysUserController.java

import cn.hutool.crypto.SecureUtil;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.cdc.oa.auth.entity.SysUser;
import com.cdc.oa.auth.service.SysUserService;
import com.cdc.oa.common.core.pojo.CommonResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**
 *
 * @author cdc
 * @since 2023-08-14
 */
@RestController
@RequestMapping("/auth/sysUser")
@Api(tags = {"系统用户对象"})
public class SysUserController {
    @Autowired
    SysUserService  sysUserService;

    @GetMapping("/getUserInfos")
    @ApiOperation(value = "获取所有系统用户信息",httpMethod = "get")
    public CommonResult getUserInfos(){
        List<SysUser> list=sysUserService.list();
        CommonResult<List<SysUser>> commonResult=new CommonResult<List<SysUser>>();
        commonResult.setCode(200);
        commonResult.setMessage("查询成功");
        commonResult.setData(list);
        return commonResult;
    }

}

4、启动SpringBoot，尝试访问http://localhost:7021/swagger-ui.html#/

页面弹框报错：

5、开始百度解决上面的问题

根据百度提示，因为我的swagger配置类和SpringBoot启动了不在一个Modul里，出现上面的问题可以通过在SpringBootApplication启动类加个注解(com.XXXXX.config是配置类所在路径包名)

@ComponentScan("com.XXXXX.config")

  6、重新启动SpringBoot，尝试访问http://localhost:7021/swagger-ui.html#/

 页面虽然进到了Swagger文档页面，但是确没有我创建的Controller对应的接口文档，提示No operations defined in spec!

说明还是有问题，还需要解决

这里尝试了几种方法都失败了，就老老实实把config移到每个Springboot模块下吧，不创建共用的config了

重新启动springboot，系统又报错了：

2023-08-25 10:22:34.770 ERROR 8996 --- [           main] s.d.s.r.o.OperationHttpMethodReader      : Invalid http method: getValid ones are [[Lorg.springframework.web.bind.annotation.RequestMethod;@666618d6]

java.lang.IllegalArgumentException: No enum constant org.springframework.web.bind.annotation.RequestMethod.get
    at java.lang.Enum.valueOf(Enum.java:238) ~[na:1.8.0_181]
    at org.springframework.web.bind.annotation.RequestMethod.valueOf(RequestMethod.java:35) ~[spring-web-5.3.24.jar:5.3.24]

又根据报错信息百度了一下，发现是 

@ApiOperation(value = "代码自动生成",httpMethod = "get")

 这个地方httpMethod = "get"这个用了小写的get，需要改成大写的

@ApiOperation(value = "代码自动生成",httpMethod = "GET")

然后再次重新启动项目， 尝试访问http://localhost:7021/swagger-ui.html#/，结果显示正确了：

 现在先这么玩吧，后面再研究下看怎么用共用的config

中途遇到的其他问题：
（1）启动Springboot报错：

2023-08-25 09:39:59.281 ERROR 11932 --- [nio-7022-exec-1] o.s.web.servlet.DispatcherServlet        : Context initialization failed

java.lang.IllegalStateException: Cannot set parent bean factory to self
    at org.springframework.beans.factory.support.AbstractBeanFactory.setParentBeanFactory(AbstractBeanFactory.java:797) ~[spring-beans-5.3.24.jar:5.3.24]
    at org.springframework.context.support.GenericApplicationContext.setParent

 此时需要再application.yml加上如下配置：

mvc:
  pathmatch:
    matching-strategy: ANT_PATH_MATCHER

（2）解决步骤（1）报错后，重新启动，仍然报错：

t.AnnotationIntrospectorPair.findPropertyInclusionByName(AnnotationIntrospectorPair.java:128) ~[jackson-databind-2.13.4.2.jar:2.13.4.2]
    at com.fasterxml.jackson.databind.cfg.MapperConfigBase.getDefaultPropertyInclusions(MapperConfigBase.java:686) ~[jackson-databind-2.13.4.2.jar:2.13.4.2]
    at com.fasterxml.jackson.databind.ser.BasicSerializerFactory.buildMapSerializer(BasicSerializerFactory.java:833) ~[jackson-databind-2.13.4.2.jar:2.13.4.2]
    at com.fasterxml.jackson.databind.ser.BasicSerializerFactory.buildContainerSerializer(BasicSerializerFactory.java:623) ~[jackson-databind-2.13.4.2.jar:2.13.4.2]
    at com.fasterxml.jackson.databind.ser.BeanSerializerFactory._createSerializer2

需要添加json依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-json</artifactId>
</dependency>