swagger-优美的Knife4j文档

ゝ一纸荒年。 2023-09-28 21:57 12阅读 0赞

### 文章目录 ###

*  1、关于 Knife4j
 *  2：由swagger-ui变为Knife4j
 *  3:配置使用Knife4j
 *   *  1:导包
     *  2:配置Knife4j配置类
     *  3:写controller
     *  4:访问Knife4j页面

系列文章：  
[swagger-springboot详解][swagger-springboot]

一般在使用 Spring Boot 开发前后端分离项目的时候，都会用到 Swagger。Swagger 是一个规范和完整的框架，用于生成、描述、调试和可视化 RESTful 风格的 Web API 服务框架。

但随着系统功能的不断增加，接口数量的爆炸式增长，Swagger 的使用体验就会变得越来越差，比如请求参数为 JSON 的时候没办法格式化，返回结果没办法折叠，还有就是没有提供搜索功能。

刚好最近发现 Knife4j 弥补了这些不足，赋予了 Swagger 更强的生命力，于是就来给大家安利一波。

# 1、关于 Knife4j #

Knife4j 的前身是 swagger-bootstrap-ui，是 springfox-swagger-ui 的增强 UI 实现。swagger-bootstrap-ui 采用的是前端 UI 混合后端 Java 代码的打包方式，在微服务的场景下显得非常臃肿，改良后的 Knife4j 更加小巧、轻量，并且功能更加强大

# 2：由swagger-ui变为Knife4j #

如果项目中之前使用过 Swagger 生成接口文档，切换到 Knife4j 可以说是非常的丝滑，只需要两步：

在 pom.xml 文件中把 springfox-boot-starter 替换为 knife4j-spring-boot-starter；

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

访问地址由原来的 http:// h o s t : \{host\}: host:\{port\}/swagger-ui.html 切换到 http:// h o s t : \{host\}: host:\{port\}/doc.html

注：如果想了解swagger-ui可以去参考[swagger-springboot详解][swagger-springboot]这个文章

# 3:配置使用Knife4j #

## 1:导包 ##

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

## 2:配置Knife4j配置类 ##

package com.wkl.swagger_demo.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.stereotype.Component;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.oas.annotations.EnableOpenApi;
    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;
    
    import java.util.ArrayList;
    
    /**
     * Description:
     * Date:       2022/6/21 - 下午 11:54
     * author:     wangkanglu
     * version:    V1.0
     */
    @Component
    //@EnableSwagger2  //开启Swagger2的自动配置
    @EnableOpenApi    //开启Knife4j配置
    public class SwaggerConfig {
    
        @Bean
        public Docket docket(){
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    // 通过.select()方法，去配置扫描接口
                    .select()
                    // RequestHandlerSelectors配置如何扫描接口
                    .apis(RequestHandlerSelectors.basePackage("com.wkl.swagger_demo.controller"))
                    .build();
        }
    
        //配置swagger-ui的api信息
        private ApiInfo apiInfo(){
            Contact contact = new Contact("联系人姓名","http://www.baidu.com/联系人连接","邮箱");
            return new ApiInfo("Swagger学习", // 标题
                    "学习演示如何配置Swagger", // 描述
                    "v1.0", // 版本
                    "http://terms.service.url/组织链接", // 组织链接
                    contact, // 联系人信息
                    "Apach 2.0 许可", // 许可
                    "许可链接", // 许可连接
                    new ArrayList<>()); // 扩展
        }
    
    }

## 3:写controller ##

package com.wkl.swagger_demo.controller;
    
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.bind.annotation.RestController;
    
    /**
     * @author wangkanglu
     * @version 1.0
     * @description
     * @date 2022-08-26 10:23
     */
    @RestController
    @RequestMapping("/hello")
    @Api(tags = "利用helloworld测试swagger")
    public class HelloController {
        
    
        @ApiOperation("获取列表方法")
        @RequestMapping(value = "/getlist",method = RequestMethod.GET)
        public String getlist(){
        
            return "getlist";
        }
    }

## 4:访问Knife4j页面 ##

直接访问Knife4j的页面：http://ip:prot/doc.html  
![在这里插入图片描述][64f26446a92a4a6da675201c9f03989d.png]

[swagger-springboot]: https://blog.csdn.net/qq_41694906/article/details/125400911?ops_request_misc=%257B%2522request%255Fid%2522%253A%2522166148238316782246410596%2522%252C%2522scm%2522%253A%252220140713.130102334.pc%255Fblog.%2522%257D&request_id=166148238316782246410596&biz_id=0&utm_medium=distribute.pc_search_result.none-task-blog-2~blog~first_rank_ecpm_v1~rank_v31_ecpm-1-125400911-null-null.nonecase&utm_term=swagger&spm=1018.2226.3001.4450
[64f26446a92a4a6da675201c9f03989d.png]: https://img-blog.csdnimg.cn/64f26446a92a4a6da675201c9f03989d.png