SpringBoot整合Swagger最新ui界面（knife4j）

 

Swagger官网地址：https://swagger.io/

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。功能主要包含以下几点:

• 使得前后端分离开发更加方便，有利于团队协作。
• 接口文档在线自动生成，降低后端开发人员编写接口文档的负担。
• 接口功能测试。

使用Swagger只需要按照它的规范去定义接口及接口相关的信息，再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，以及在线接口调试页面等等。

Knife4j（小刀 four java，log4j哈哈）

如果直接使用Swagger，需要按照Swagger的规范定义接口，实际上就是编写Json文件，编写起来比较繁琐、并不方便。

而在项目中使用，我们一般会选择一些现成的框架来简化文档的编写，而这些框架是基于Swagger的（例如 knife4j)。

Knife4j是一款基于Swagger的增强工具，官网地址：https://doc.xiaominfo.com/

 

使用knife4j只需在pom.xml中引入如下依赖即可：

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

1. 使用方式

1、导入knife4j起步依赖:

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

2、编写Swagger配置类:

package com.baidou.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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2配置类（生成接口文档）
 *
 * @author 白豆五
 * @version 2023/1/21
 * @since JDK8
 */
@Configuration
@EnableSwagger2 //开启swagger2注解支持
@EnableKnife4j  //开启Knife4j注解支持
public class SwaggerConfig {
    @Bean
    public Docket webApiConfig() { //生成接口文档的清单
        // 文档类型
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                //指定controller包扫描路径
                .apis(RequestHandlerSelectors.basePackage("com.baidou.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    //配置api信息
    private ApiInfo webApiInfo() {
        return new ApiInfoBuilder()
                .title("网站-API文档")
                .description("本文档描述了xxx管理系统微服务接口定义")
                .version("1.0")
                .contact(new Contact("白豆五", "https://blog.csdn.net/qq_46921028", "13212341234@163.com"))
                .build();
    }
}

注意： Docket声明时，有一个包扫描的路径，该路径指定的是Controller所在包的路径。因为Swagger在生成接口文档时，就是根据这里指定的包路径，自动的扫描该包下的@Controller， @RestController， @RequestMapping等SpringMVC的注解，依据这些注解来生成对应的接口文档。

3、 设置静态资源映射（对Swagger的静态资源放行）

由于Swagger生成的在线文档中，涉及到很多静态资源，这些静态资源需要添加静态资源映射，否则接口文档页面无法访问。

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    // 静态资源放行
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/web/**").addResourceLocations("classpath:/web/");
        
        // 对swaggger静态资源放行
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        
    }
}

如果配置拦截器，需要对以下资源放行：

"/doc.html",
"/webjars/**",
"/swagger-resources",
"/v2/api-docs"

4、访问swagger：http://localhost:8081/doc.html

 

 

2. 常用注解

Swagger提供了很多的注解，通过这些注解，我们可以更好更清晰的描述我们的接口，包含接口的请求参数、响应数据、数据模型等。核心的注解，主要包含以下几个：

注解	位置	说明
@Api	类	添加到Controller类上，表示对类的说明
@ApiModel	类(通常是实体类)	描述实体类的作用
@ApiModelProperty	属性	描述实体类的属性
@ApiOperation	方法	说明方法的用途、作用
@ApiImplicitParams	方法	表示一组参数说明
@ApiImplicitParam	方法	用在@ApiImplicitParams注解中，指定一个请求参数的各个方面的属性
@ApiParam	方法形参上	描述接口方法的形参

示例：注解的使用

在实体类中使用：

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("学生实体类")
public class Stu implements Serializable {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty("主键")
    private Long id;

    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("密码")
    private String password;

    @ApiModelProperty("年龄")
    private Integer age;

    @ApiModelProperty("电话")
    private String tel;
}

在Controller类中使用：
 

@RestController
@RequestMapping("/stu")
@Api(tags = "学生相关接口")
public class StuController {

    @Autowired
    StuMapper stuMapper;

    @GetMapping("/list")
    @ApiOperation(value = "获取学生列表接口")
    public String findList() {
        List<Stu> list = stuMapper.selectAll();
        return JSON.toJSONString(list);
    }

    @GetMapping()
    @ApiOperation(value = "通过名字获取学生列表接口")
    // required = true 表示必须传递参数
    public String select( @ApiParam(value = "学生姓名",required = true) @RequestParam String name) {
        List<Stu> list = stuMapper.select(name);
        return JSON.toJSONString(list);
    }


    @DeleteMapping("/{id}")
    @ApiOperation(value = "通过id删除学生信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "学生的id",required = true),
    })
    public String delete(@PathVariable Long id) {
        int row = stuMapper.deleteStu(id);
        return row == 1 ? "ok" : "error";
    }


    @PostMapping("/save")
    @ApiOperation(value = "新增学生信息")
    public String save(@ApiParam("学生信息") @RequestBody Stu stu) {
        int row = stuMapper.save(stu);
        return row == 1 ? "ok" : "error";
    }

    @PutMapping("/update")
    @ApiOperation(value = "修改学生信息")
    public String update(@ApiParam("学生信息")@RequestBody Stu stu) {
        int row = stuMapper.update(stu);
        return row == 1 ? "ok" : "error";
    }
}

 只需使用Swagger提供的注解便可生成接口文档。