SpringBoot集成swagger

一、swagger简介

简单说明一下，Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。

二、SpringBoot集成swagger

本次集成使用springboot + maven 构建的web项目。

第一步：

pom文件引入依赖

      <!-- swagger2 -->
      <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

       <!-- swagger2官方UI --> 
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

        <!-- 第三方UI -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency> 

第二步：

写配置文件

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @description: Swagger2配置类
 * @author: WhiteCrowZHZ
 * @date: 2022/2/16 7:52
 */

@Configuration
@EnableSwagger2
public class Swagger2 {

    /**
     * 配置swagger2核心配置
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2) // 指定api类型为swagger2
                .apiInfo(apiInfo()) // 定义api文档汇总信息
                .select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) // 指定需要提供文档的Controller类所在的包
                .paths(PathSelectors.any()) // 需要生成文档的接口路径
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("这是接口文档页的标题")
                .contact(new Contact(
                        "name",
                        "http://example.com",
                        "example@qq.com"))
                .description("这是一段关于接口文档的描述信息")
                .version("1.0.1")
                .termsOfServiceUrl("http://example.com")
                .build();
    }


}

第三步：

接口类上增加相关注解

import com.example.demo.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;

import java.io.Serializable;
import java.util.HashMap;
import java.util.Map;


@RestController
@Api(value = "UserCacheController ")
public class UserCacheController {

    //@Autowired
    //private StringRedisTemplate stringRedisTemplate;

    @Autowired
    private RedisTemplate<String, Serializable> redisCacheTemplate;

    /**
     * 获取缓存信息
     * @param id
     * @return
     */
    @ApiOperation(value = "从缓存中获取用户信息")
    @GetMapping(value = "/cache/user/getCacheUser/{id}")
    @ResponseBody
    public Map<String, Object> getCacheUser(@PathVariable Long id) {
        Map<String, Object> result = new HashMap<String, Object>();
        result.put("code", "000000");
        result.put("msg", "success");
        User u =  (User) redisCacheTemplate.opsForValue().get(String.valueOf(1));
        System.out.println(u.getUserName());
        result.put("body", u);
        return result;
    }

    @ApiOperation(value = "将用户信息存入缓存")
    @GetMapping(value = "/cache/user/cacheUser")
    @ResponseBody
    public Map<String, Object> cacheUser() {
        Map<String, Object> result = new HashMap<String, Object>();
        result.put("code", "000000");
        result.put("msg", "success");
        User u = new User();
        u.setId("1");
        u.setAge("23");
        u.setUserName("huangjinjin");
        result.put("body", u);
        redisCacheTemplate.opsForValue().set(String.valueOf(u.getId()), u);
        return result;
    }

}

注意这里的@Api注解，写在类上的，与我们的配置类相对应。介绍一下相关的注解

@Api： 描述 Controller

@ApiIgnore： 忽略该 Controller，指不对当前类做扫描

@ApiOperation： 描述 Controller类中的 method接口

@ApiParam： 单个参数描述，与@ApiImplicitParam不同的是，他是写在参数左侧的。如（ @ApiParam(name="username",value="用户名")Stringusername）

@ApiModel： 描述 POJO对象

@ApiProperty： 描述 POJO对象中的属性值

@ApiImplicitParam： 描述单个入参信息

@ApiImplicitParams： 描述多个入参信息

@ApiResponse： 描述单个出参信息

@ApiResponses： 描述多个出参信息

@ApiError： 接口错误所返回的信息

接下来就是启动项目，访问http://localhost:8885/swagger-ui.html这个地址，这里的8885是我的项目设置端口号.

三、出现的问题

出现原因分析

本人的springboot版本是最新的2.6.9，swagger版本是2.9.2，按着网上的步骤进行环境配置，但在运行时却会出现Failed to start bean ‘documentationPluginsBootstrapper’的问题，在排查了多方原因后，我发现是springboot的版本更新，导致的swagger2的异常

解决方法

（本人的解决方法）在application.properties文件里增加配置：

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

原因是在springboot2.6.6中将SpringMVC 默认路径匹配策略从AntPathMatcher 更改为PathPatternParser，导致出错，解决办法是切换回原先的AntPathMatcher

参考 https://blog.csdn.net/yangzhanghui/article/details/124063438