还在用swagger 你out了，knife4j在你生成接口文档的道路助你一臂之力

╰+攻爆jí腚メ 2023-10-02 15:17 3阅读 0赞

### knife4j： ###

*  (1)简介
 *  (2)核心功能
 *  (3) 快速集成knife4j
 *   *  第一步：在maven项目的pom.xml中引入Knife4j的依赖包，代码如下：
     *  第二步：创建Swagger配置依赖，代码如下：
     *  第三步：添加相关测试
 *  （4）Swagger常用注解

# (1)简介 #

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

[gitee地址][gitee]

[官方文档][Link 1]

[效果演示][Link 2]  
官方文档很全，建议参考官方出品

# (2)核心功能 #

该UI增强包主要包括两大核心功能：文档说明 和 在线调试

*  文档说明：根据Swagger的规范说明，详细列出接口文档的说明，包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息，使用swagger-bootstrap-ui能根据该文档说明，对该接口的使用情况一目了然。
 *  在线调试：提供在线接口联调的强大功能，自动解析当前接口参数,同时包含表单验证，调用参数可返回接口响应内容、headers、Curl请求命令实例、响应时间、响应状态码等信息，帮助开发者在线调试，而不必通过其他测试工具测试接口是否正确,简介、强大。
 *  个性化配置：通过个性化ui配置项，可自定义UI的相关显示信息
 *  离线文档：根据标准规范，生成的在线markdown离线文档，开发者可以进行拷贝生成markdown接口文档，通过其他第三方markdown转换工具转换成html或pdf，这样也可以放弃swagger2markdown组件
 *  接口排序：自1.8.5后，ui支持了接口排序功能，例如一个注册功能主要包含了多个步骤,可以根据swagger-bootstrap-ui提供的接口排序规则实现接口的排序，step化接口操作，方便其他开发者进行接口对接

# (3) 快速集成knife4j #

本次示例使用Spring Boot作为脚手架来快速集成Knife4j,Spring Boot版本2.5.6,Knife4j版本3.0.3

## 第一步：在maven项目的pom.xml中引入Knife4j的依赖包，代码如下： ##

<dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
                <version>2.5.6</version>
            </dependency>
            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>knife4j-spring-boot-starter</artifactId>
                <version>3.0.3</version>
            </dependency>
        </dependencies>

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

@Configuration
    @EnableSwagger2 //Springfox-swagger框架提供的使用Swagger注解，该注解必须加
    @EnableKnife4j //knife4j提供的增强注解,Ui提供了例如动态参数、参数过滤、接口排序等增强功能,如果你想使用这些增强功能就必须加该注解，否则可以不用加
    public class Knife4jConfig implements WebMvcConfigurer {
        
    
        @Bean
        public Docket createRestApi() {
        
            return new Docket(DocumentationType.OAS_30).pathMapping("/")
                    .enable(true) // 定义是否开启swagger，false为关闭，可以通过变量控制
                    .apiInfo(apiInfo()) // 将api的元信息设置为包含在json ResourceListing响应中。
                    .host("http://localhost:8080") //接口调试地址
                    .select() // 选择哪些接口作为swagger的doc发布
    //                .apis(RequestHandlerSelectors.any())
    //                指定扫描路径
    //                .apis(RequestHandlerSelectors.basePackage("com.ats.datacenter.web.controller.registrationfrom"))
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //指定扫描的注解类型
                    .paths(PathSelectors.any())//指定某个路径才能生成swagger
                    .build()
                    .protocols(newHashSet("https", "http"))  // 支持的通讯协议集合
                    .securitySchemes(securitySchemes()) // 授权信息设置，必要的header token等认证信息
                    .securityContexts(securityContexts());// 授权信息全局应用
        }
    
        /**
         * API 页面上半部分展示信息
         */
        private ApiInfo apiInfo() {
        
            return new ApiInfoBuilder().title("快速开始" + " Api Doc")
                    .description("接口文档")
                    .contact(new Contact("百度", "www.baidu.com", "123456@qq.com"))
                    .version("1.0.0.0")
                    .build();
        }
    
        /**
         * 设置授权信息
         */
        private List<SecurityScheme> securitySchemes() {
        
            ApiKey apiKey = new ApiKey("BearerToken", "Authorization", In.HEADER.toValue());
            return Collections.singletonList(apiKey);
        }
    
        /**
         * 授权信息全局应用
         */
        private List<SecurityContext> securityContexts() {
        
            return Collections.singletonList(
                    SecurityContext.builder()
                            .securityReferences(Collections.singletonList(new SecurityReference("BearerToken", new AuthorizationScope[]{
        new AuthorizationScope("global", "")})))
                            .build()
            );
        }
    
    
        @SafeVarargs
        private final <T> Set<T> newHashSet(T... ts) {
        
            if (ts.length > 0) {
        
                return new LinkedHashSet<>(Arrays.asList(ts));
            }
            return null;
        }
        /**
         * 通用拦截器排除swagger设置，所有拦截器都会自动加swagger相关的资源排除信息
         */
        @SuppressWarnings("unchecked")
        @Override
        public void addInterceptors(InterceptorRegistry registry) {
        
            try {
        
                Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
                List<InterceptorRegistration> registrations = (List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
                if (registrations != null) {
        
                    for (InterceptorRegistration interceptorRegistration : registrations) {
        
                        interceptorRegistration
                                .excludePathPatterns("/swagger**/**")
                                .excludePathPatterns("/webjars/**")
                                .excludePathPatterns("/v3/**");
    //                    .excludePathPatterns("/doc.html");
                    }
                }
            } catch (Exception e) {
        
                e.printStackTrace();
            }
        }
    
    }

## 第三步：添加相关测试 ##

实体类：

package com.example.demo.vo;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    @Data
    @ApiModel(value = "用户实体")
    public class User {
        
    
        @ApiModelProperty(value = "id")
        private Integer id;
    
        @ApiModelProperty(value = "用户名")
        private  String username;
    
        @ApiModelProperty(value = "性别，0男，1女")
        private Integer sex;
    
    }

controller：

package com.example.demo.controller;
    
    
    import com.example.demo.vo.User;
    import io.swagger.annotations.*;
    import org.springframework.web.bind.annotation.*;
    import springfox.documentation.annotations.ApiIgnore;
    
    @RestController
    @Api(tags = "用户接口")//描述UserController的信息
    public class UserController {
        
     
        @ApiOperation(value = "查询用户",notes = "根据id查询用户")
        @ApiImplicitParam(paramType = "path",name="id",value = "用户id",required = true)
        @GetMapping("/user/query/{id}")
        public String getUserById(@PathVariable Integer id) {
        
            return "/user/"+id;
        }
    
        @ApiResponses({
        
                @ApiResponse(code=200,message="删除成功"),
                @ApiResponse(code=500,message="删除失败")})
        @ApiOperation(value = "删除用户",notes = "根据id删除用户")
        @DeleteMapping("/user/delete/{id}")
        public Integer deleteUserById(@PathVariable Integer id) {
        
            return id;
        }
    
        @ApiOperation(value = "添加用户",notes = "添加一个用户，传入用户名和性别")
        @ApiImplicitParams({
        
                @ApiImplicitParam(paramType = "query",name="username",value = "用户名",required = true,defaultValue = "张三"),
                @ApiImplicitParam(paramType = "query",name="sex",value = "性别",required = true,defaultValue = "女")
        })
        @PostMapping("/user")
        public String addUser(@RequestParam String username,@RequestParam String sex){
        
            return username+","+sex;
        }
    
        @ApiOperation(value="修改用户",notes = "根据传入的用户信息修改用户")
        @PutMapping("/user")
        public String updateUser(@RequestBody User user){
        
            return user.toString();
        }
    
        @GetMapping("/ignore")
        @ApiIgnore
        public void ignoreMethod(){
        }
    
    }

输入访问地址： http://127.0.0.1:8080/doc.html\#/home  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5LyP5Yqg54m56YGH5LiK6KW_5p-a_size_20_color_FFFFFF_t_70_g_se_x_16]

# （4）Swagger常用注解 #

在Java类中添加Swagger的注解即可生成Swagger接口文档，常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数的描述信息

@ApiModel：用对象来接收参数

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiImplicitParam：一个请求参数

@ApiImplicitParams：多个请求参数的描述信息

@ApiImplicitParam属性：  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5LyP5Yqg54m56YGH5LiK6KW_5p-a_size_20_color_FFFFFF_t_70_g_se_x_16 1]

[gitee]: https://gitee.com/xiaoym/knife4j
[Link 1]: https://doc.xiaominfo.com/
[Link 2]: http://knife4j.xiaominfo.com/doc.html
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5LyP5Yqg54m56YGH5LiK6KW_5p-a_size_20_color_FFFFFF_t_70_g_se_x_16]: https://img-blog.csdnimg.cn/8356c09b84234037814ac765efb2341f.png?x-oss-process=image/watermark,type_ZHJvaWRzYW5zZmFsbGJhY2s,shadow_50,text_Q1NETiBA5LyP5Yqg54m56YGH5LiK6KW_5p-a,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5LyP5Yqg54m56YGH5LiK6KW_5p-a_size_20_color_FFFFFF_t_70_g_se_x_16 1]: https://img-blog.csdnimg.cn/eba35a5e950942b78118f32ef761e396.png?x-oss-process=image/watermark,type_ZHJvaWRzYW5zZmFsbGJhY2s,shadow_50,text_Q1NETiBA5LyP5Yqg54m56YGH5LiK6KW_5p-a,size_20,color_FFFFFF,t_70,g_se,x_16