[Java知识库]SpringBoot整合Swagger

SpringBoot整合Swagger

1、swagger配置类

我们引入的是knife4j,knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!

第一步，需要在pom中引入相应的配置，这里我们使用3.0.3

<!--swagger依赖-->
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-spring-boot-starter</artifactId>
	<version>3.0.3</version>
</dependency>

第二步 在代码中加入相应的配置，新建config包，写入swaggerConfig配置类：

package com.chen.springboot.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
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;

/**
 * @author java小豪
 * @version 1.0.0
 * @description swagger配置类
 */
@Configuration
@EnableKnife4j
public class SwaggerConfig {

    /**
     *
     * @return
     */
    @Bean
    public Docket restApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("研发组")
                .apiInfo(apiInfo("Spring Boot 使用Swagger构建RestFul APIs", "1.0"))
                .useDefaultResponseMessages(true)
                .forCodeGeneration(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chen.springboot.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://localhost:9999/doc.html
     * @param title
     * @param version
     * @return
     */
    private ApiInfo apiInfo(String title, String version) {
        return new ApiInfoBuilder()
                .title(title)
                .description("更多请关注：https://blog.csdn.net/qq_51929833")
                .termsOfServiceUrl("https://blog.csdn.net/qq_51929833")
                .contact(new Contact("java小豪", "https://blog.csdn.net/qq_51929833", "javaxiaohao@163.com"))
                .version(version)
                .build();
    }

}

注意：

.apis(RequestHandlerSelectors.basePackage(“com.chen.springboot.controller”))这个配置是用来指定我们的接口层的位置，大家可以根据你自己项目的实际情况来进行修改。.apiInfo()是定义一些我们项目的描述信息，可以根据实际需要在参数中修改。需要注意的是配置类的头部需要加上@Configuration，声明配置类，以及@EnableKnife4j加载swagger的一些相关配置。

2、使用swagger

我们在刚才指定的接口层使用swagger来说明接口的使用方法

import com.chen.springboot.entity.User;
import com.chen.springboot.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * @author java小豪
 * @version 1.0.0
 * @description 用户controller类
 */
@RestController
@RequestMapping("/user")
@Api(tags = "用户接口层")
public class UserController {

    @Resource
    private UserService userService;

    /**
     * 新增或更新用户
     * @param user 用户
     * @return
     */
    @PostMapping
    @ApiModelProperty(value = "新增或更新用户")
    public Boolean saveUser(
            @ApiParam(name = "用户实体", defaultValue = "{}")
            @RequestBody User user) {
        return userService.saveUser(user);
    }
}

配置完之后启动项目

启动时报错了：

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
	at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:181) ~[spring-context-5.3.23.jar:5.3.23]
	at org.springframework.context.support.DefaultLifecycleProcessor.access$200(DefaultLifecycleProcessor.java:54) ~[spring-context-5.3.23.jar:5.3.23]
	at org.springframework.context.support.DefaultLifecycleProcessor$LifecycleGroup.start(DefaultLifecycleProcessor.java:356) ~[spring-context-5.3.23.jar:5.3.23]
	at java.lang.Iterable.forEach(Iterable.java:75) ~[na:1.8.0_333]
	at org.springframework.context.support.DefaultLifecycleProcessor.startBeans(DefaultLifecycleProcessor.java:155) ~[spring-context-5.3.23.jar:5.3.23]
	at org.springframework.context.support.DefaultLifecycleProcessor.onRefresh(DefaultLifecycleProcessor.java:123) ~[spring-context-5.3.23.jar:5.3.23]
	at org.springframework.context.support.AbstractApplicationContext.finishRefresh(AbstractApplicationContext.java:935) ~[spring-context-5.3.23.jar:5.3.23]
	at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:586) ~[spring-context-5.3.23.jar:5.3.23]
	at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:145) ~[spring-boot-2.6.12.jar:2.6.12]
	at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:745) [spring-boot-2.6.12.jar:2.6.12]
	at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:420) [spring-boot-2.6.12.jar:2.6.12]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:307) [spring-boot-2.6.12.jar:2.6.12]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1317) [spring-boot-2.6.12.jar:2.6.12]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1306) [spring-boot-2.6.12.jar:2.6.12]

如图：

原因：

• https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-2.6-Release-Notes

• 在SpringBoot2.6之后，Spring MVC 处理程序映射匹配请求路径的默认策略已从 AntPathMatcher 更改为PathPatternParser。如果需要切换为AntPathMatcher，官方给出的方法是配置spring.mvc.pathmatch.matching-strategy=ant_path_matcher

• 但是actuator endpoints在2.6之后也使用基于 PathPattern 的 URL 匹配，而且actuator endpoints的路径匹配策略无法通过配置属性进行配置，如果同时使用Actuator和Springfox，会导致程序启动失败，所以只是进行上面的设置是不行的。

解决办法：

我们只需要在application.yml中添加配置即可

spring:
	mvc:
		path-match:
			matching-strategy: ant_path_matcher