[Java知识库]springboot 集成swagger

前言

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

knife4j的前身是swagger-bootstrap-ui，为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j

更名后主要专注的方面

• 前后端Java代码以及前端Ui模块进行分离,在微服务架构下使用更加灵活
• 提供专注于Swagger的增强解决方案,不同于只是改善增强前端Ui部分

swagger有什么用呢？能做什么？

• 支持 API 自动生成同步的在线文档：使用 Swagger后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
• 提供 Web 页面在线测试 API：光有文档还不够，Swagger生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

快速开始

业务场景：不使用增强功能,纯粹换一个swagger的前端皮肤

不使用增强功能,纯粹换一个swagger的前端皮肤，这种情况是最简单的,你项目结构下无需变更

可以直接引用swagger-bootstrap-ui的最后一个版本1.9.6或者使用knife4j-spring-ui

第一步：创建Spring Boot项目并且在pom.xml中引入Knife4j的依赖包，Maven坐标如下：

老版本引用

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

新版本引用

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>3.0.3</version>
</dependency>

Spring Boot项目单体架构使用增强功能

在Spring Boot单体架构下,knife4j提供了starter供开发者快速使用

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

该包会引用所有的knife4j提供的资源，包括前端Ui的jar包

第二步：创建Swagger配置依赖，代码如下

@Configuration
@EnableKnife4j
public class Knife4jConfiguration {

    @Bean(value = "dockerBean")
    public Docket dockerBean() {
        //指定使用Swagger2规范
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                //描述字段支持Markdown语法
                .description("# Knife4j RESTful APIs")
                .termsOfServiceUrl("https://doc.xiaominfo.com/")
                .contact("xiaoymin@foxmail.com")
                .version("1.0")
                .build())
                //分组名称
                .groupName("用户服务")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
                .paths(PathSelectors.any())
                .build()
                // 加入请求头
                .globalRequestParameters(getParameter());;
        return docket;
    }
    // 加入请求头，一般情况不加该配置
    private List<RequestParameter> getParameter(){

        RequestParameterBuilder requestParameterBuilder = new RequestParameterBuilder();
        List<RequestParameter> parameters = new ArrayList<>();
        requestParameterBuilder
                .name("token")
                .description("令牌")
                .required(false)
                .in(ParameterType.HEADER)
                .build();
        parameters.add(requestParameterBuilder.build());
        return parameters;
    }
}

提示信息
如果开发者使用的是Knife4j 2.x版本，并且Spring Boot版本高于2.4,那么需要在Spring Boot的yml文件中做如下配置：

spring:
    mvc:
        pathmatch:
            # 配置策略
            matching-strategy: ant-path-matcher

第三步:新建一个接口Controller类，如下：

@Api(tags = "测试")
@RestController
@RequestMapping("test")
public class TestController {

    @ApiOperation("测试样例")
    @GetMapping("/demo")
    public void test(){
        System.out.println("测试swagger");
    }
}

测试样例，启动项目，访问默认地址 http://localhost:8080/doc.html，成功

F&Q

访问地址后，访问不到资源提示Knife4j 文档请求异常，或者是控制台出现资源找不到404 的问题
加入资源加载器配置,重定向静态资源加载位置。

@Component
public class WebMvcConfiguration implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {

        // 解决静态资源无法访问
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

    }
}

可以看到静态资源在这个knife4j-spring-ui-3.0.3.jar包的resources 文件夹下。