springboot集成swagger

一、什么是swagger？

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

二、如何使用？

使用的spring boot+maven构建的web项目，所以我们的步骤是：

第一步，pom文件中引入依赖

<!--集成swagger-->
<!--swagger依赖google的guava-->
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>25.1-jre</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

第二步，写配置文件

package com.example.demo.config;

import io.swagger.annotations.Api;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * swagger配置类
 */
@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    //基本信息的配置，信息会在api文档上显示
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("测试的接口文档")
                .description("xx相关接口的文档")
                .termsOfServiceUrl("http://localhost:8080/hello")
                .version("1.0")
                .build();
    }


    /**
     * apiInfo：api基本信息的配置，信息会在api文档上显示，可有选择的填充，比如配置文档名称、项目版本号等
     * apis：使用什么样的方式来扫描接口，RequestHandlerSelectors下共有五种方法可选。我们当前使用通过在类前添加@Api注解的方式，其他方法我们后续介绍。
     * path：扫描接口的路径，PathSelectors下有四种方法，我们这里是全扫
     * @return
     */
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }
}

第三步：接口类上增加相关的注解

package com.example.demo.controller;

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.htmll这个地址，这里的8885是我的项目设置端口号.

三、出现的问题

出现原因分析

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

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.6.6</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

解决方法

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

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

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

参考资料：

spring boot项目中使用swagger2 - 简书

（已解决）Failed to start bean ‘documentationPluginsBootstrapper’_FFFPAG的博客-CSDN博客