😊 @ 作者： Eric

💖 @ 主页： https://blog.csdn.net/weixin_47316183?type=blog

🎉 @ 主题：SpringBoot整合knife4j（快速入门超详细版）

⏱️ @ 创作时间： 2023年08月01日

文章目录

• 1、什么是Knife4j
• 2、SpringBoor整合Knife4j
• • 2.1、Knife4j配置
  • 2.2、使用Knife4j
  • 2.3、效果
  • 总结

    ---

    1、什么是Knife4j

    在日常开发中，写接口文档是我们必不可少的，而Knife4j就是一个接口文档工具，可以看作是Swagger的升级版，但是界面比Swagger更好看，功能更丰富

    早期，swagger-boostrap-ui是1.x版本，如今swagger-bootsrap-ui到2.x，同时也更改名字Knife4j，适用于单体和微服务项目。

    Knife4j官方网站：https://doc.xiaominfo.com/

    2、SpringBoor整合Knife4j

    2.1、Knife4j配置

    1、创建一个SpringBoot项目

    

    2、引入Knife4j相关依赖（这里顺带引入了Lombok依赖）

    
        com.github.xiaoymin
        knife4j-spring-boot-starter
        2.0.8
    
    
        org.projectlombok
        lombok
    
    

    3、创建Knife4J配置类

    package com.eric.springbootknife4j.config;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.ParameterBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.schema.ModelRef;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.service.Parameter;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
    import java.util.ArrayList;
    import java.util.List;
    /**
     * Swagger2配置信息
     * 这里分了两组显示
     * 第一组是api，当作用户端接口
     * 第二组是admin，当作后台管理接口
     * 也可以根据实际情况来减少或者增加组
     *
     * @author Eric
     * @date 2023-07-30 22:17
     */
    @Configuration
    @EnableSwagger2WebMvc
    public class Swagger2Config {
        private ApiInfo adminApiInfo() {
            return new ApiInfoBuilder()
                    .title("Eric-SpringBoot整合Knife4j-API文档")
                    .description("本文档描述了SpringBoot如何整合Knife4j")
                    .version("1.0")
                    .contact(new Contact("Eric", "https://blog.csdn.net/weixin_47316183?type=blog", "ericsyn@foxmail.com"))
                    .build();
        }
        private ApiInfo webApiInfo() {
            return new ApiInfoBuilder()
                    .title("Eric-SpringBoot整合Knife4j-API文档")
                    .description("本文档描述了SpringBoot如何整合Knife4j")
                    .version("1.0")
                    .contact(new Contact("Eric", "https://blog.csdn.net/weixin_47316183?type=blog", "ericsyn@foxmail.com"))
                    .build();
        }
        /**
         * 第一组：api
         * @return
         */
        @Bean
        public Docket webApiConfig() {
            List pars = new ArrayList<>();
            ParameterBuilder tokenPar = new ParameterBuilder();
            tokenPar.name("userId")
                    .description("用户token")
                    //.defaultValue(JwtHelper.createToken(1L, "admin"))
                    .defaultValue("1")
                    .modelRef(new ModelRef("string"))
                    .parameterType("header")
                    .required(false)
                    .build();
            pars.add(tokenPar.build());
            Docket webApi = new Docket(DocumentationType.SWAGGER_2)
                    .groupName("用户端接口")
                    .apiInfo(webApiInfo())
                    .select()
                    //只显示api路径下的页面
                    .apis(RequestHandlerSelectors.basePackage("com.eric.springbootknife4j"))
                    .paths(PathSelectors.regex("/api/.*"))
                    .build()
                    .globalOperationParameters(pars);
            return webApi;
        }
        /**
         * 第二组：admin
         * @return
         */
        @Bean
        public Docket adminApiConfig() {
            List pars = new ArrayList<>();
            ParameterBuilder tokenPar = new ParameterBuilder();
            tokenPar.name("adminId")
                    .description("用户token")
                    .defaultValue("1")
                    .modelRef(new ModelRef("string"))
                    .parameterType("header")
                    .required(false)
                    .build();
            pars.add(tokenPar.build());
            Docket adminApi = new Docket(DocumentationType.SWAGGER_2)
                    .groupName("后台接口")
                    .apiInfo(adminApiInfo())
                    .select()
                    //只显示admin路径下的页面
                    .apis(RequestHandlerSelectors.basePackage("com.eric.springbootknife4j"))
                    .paths(PathSelectors.regex("/admin/.*"))
                    .build()
                    .globalOperationParameters(pars);
            return adminApi;
        }
    }
    

    2.2、使用Knife4j

    1、创建一个实体类

    package com.eric.springbootknife4j.entity;
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Builder;
    import lombok.Data;
    /**
     * @author Eric
     * @date 2023-07-31 9:55
     */
    @ApiModel("用户实体类")
    @Data
    @Builder
    public class SwaggerUser {
        @ApiModelProperty("用户Id")
        private Long id;
        @ApiModelProperty("用户名称")
        private String name;
    }
    

    2、对应接口，这里我为了大家看的方便，也是分了两个控制器，也是根据api和admin来分的

    

    admin

    package com.eric.springbootknife4j.admin;
    import com.eric.springbootknife4j.entity.SwaggerUser;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import io.swagger.annotations.ApiParam;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    import java.util.ArrayList;
    import java.util.List;
    /**
     * @author Eric
     * @date 2023-07-31 9:50
     */
    @Api(tags = "用户端控制器")
    @RestController
    @RequestMapping("/admin")
    public class AdminController {
        @ApiOperation(value = "获取数据")
        @GetMapping("/test")
        public List test(@ApiParam(name = "id",value = "用户Id") Long id,
                                      @ApiParam(name = "name",value = "用户名称") String name){
            List list = new ArrayList<>();
            list.add(SwaggerUser.builder().id(id).name(name).build());
            return list;
        }
    }
    

    api

    package com.eric.springbootknife4j.api;
    import com.eric.springbootknife4j.entity.SwaggerUser;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import io.swagger.annotations.ApiParam;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    import java.util.ArrayList;
    import java.util.List;
    /**
     * @author Eric
     * @date 2023-07-31 9:50
     */
    @Api(tags = "用户端控制器")
    @RestController
    @RequestMapping("/api")
    public class ApiController {
        @ApiOperation(value = "获取数据")
        @GetMapping("/test")
        public List test(@ApiParam(name = "id",value = "用户Id") Long id,
                                      @ApiParam(name = "name",value = "用户名称") String name){
            List list = new ArrayList<>();
            list.add(SwaggerUser.builder().id(id).name(name).build());
            return list;
        }
    }
    

    2.3、效果

    此时运行项目，访问 IP+端口/doc.html

    例如：http://127.0.0.1:8080/doc.html

    
    

    这就是首页

    

    包括也是按照我们的配置文件来分组显示了，这里可根据自己项目的实际情况，按照微服务来分、按照功能目录来分都是可以的

    

    如下就是我们的实体类，发现我们写的注释也都自动生成了

    

    下面就是我们的接口调试界面了

    

    自带路径、接口说明、参数说明，只要我们写了解释，这里都会显示

    此时我们也可以点击调试，然后点击发送，就能看到我们的返回信息了，并且如果我们的返回实体类上有注解注释的，这里也是会显示的

    

    ---

    总结

    怎么样，是不是特别的方便和简单~

     
     深圳网站制作公司  湖南官网网站推广软件  贵阳网站制作建设  赣州人才网官网  电商平台建设  多少钱