SpringBoot整合knife4j（快速入门超详细版）

在这里插入图片描述
😊 @ 作者： Eric
💖 @ 主页： https://blog.csdn.net/weixin_47316183?type=blog
🎉 @ 主题：SpringBoot整合knife4j（快速入门超详细版）
⏱️ @ 创作时间： 2023年08月01日

在这里插入图片描述

文章目录

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依赖）

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.8</version></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></dependency>

3、创建Knife4J配置类

packagecom.eric.springbootknife4j.config;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importspringfox.documentation.builders.ApiInfoBuilder;importspringfox.documentation.builders.ParameterBuilder;importspringfox.documentation.builders.PathSelectors;importspringfox.documentation.builders.RequestHandlerSelectors;importspringfox.documentation.schema.ModelRef;importspringfox.documentation.service.ApiInfo;importspringfox.documentation.service.Contact;importspringfox.documentation.service.Parameter;importspringfox.documentation.spi.DocumentationType;importspringfox.documentation.spring.web.plugins.Docket;importspringfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;importjava.util.ArrayList;importjava.util.List;/**
 * Swagger2配置信息
 * 这里分了两组显示
 * 第一组是api，当作用户端接口
 * 第二组是admin，当作后台管理接口
 * 也可以根据实际情况来减少或者增加组
 *
 * @author Eric
 * @date 2023-07-30 22:17
 */@Configuration@EnableSwagger2WebMvcpublicclassSwagger2Config{privateApiInfoadminApiInfo(){returnnewApiInfoBuilder().title("Eric-SpringBoot整合Knife4j-API文档").description("本文档描述了SpringBoot如何整合Knife4j").version("1.0").contact(newContact("Eric","https://blog.csdn.net/weixin_47316183?type=blog","[email protected]")).build();}privateApiInfowebApiInfo(){returnnewApiInfoBuilder().title("Eric-SpringBoot整合Knife4j-API文档").description("本文档描述了SpringBoot如何整合Knife4j").version("1.0").contact(newContact("Eric","https://blog.csdn.net/weixin_47316183?type=blog","[email protected]")).build();}/**
     * 第一组：api
     * @return
     */@BeanpublicDocketwebApiConfig(){List<Parameter> pars =newArrayList<>();ParameterBuilder tokenPar =newParameterBuilder();
        tokenPar.name("userId").description("用户token")//.defaultValue(JwtHelper.createToken(1L, "admin")).defaultValue("1").modelRef(newModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());Docket webApi =newDocket(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
     */@BeanpublicDocketadminApiConfig(){List<Parameter> pars =newArrayList<>();ParameterBuilder tokenPar =newParameterBuilder();
        tokenPar.name("adminId").description("用户token").defaultValue("1").modelRef(newModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());Docket adminApi =newDocket(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、创建一个实体类

packagecom.eric.springbootknife4j.entity;importio.swagger.annotations.ApiModel;importio.swagger.annotations.ApiModelProperty;importlombok.Builder;importlombok.Data;/**
 * @author Eric
 * @date 2023-07-31 9:55
 */@ApiModel("用户实体类")@Data@BuilderpublicclassSwaggerUser{@ApiModelProperty("用户Id")privateLong id;@ApiModelProperty("用户名称")privateString name;}

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

admin

packagecom.eric.springbootknife4j.admin;importcom.eric.springbootknife4j.entity.SwaggerUser;importio.swagger.annotations.Api;importio.swagger.annotations.ApiOperation;importio.swagger.annotations.ApiParam;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestMapping;importorg.springframework.web.bind.annotation.RestController;importjava.util.ArrayList;importjava.util.List;/**
 * @author Eric
 * @date 2023-07-31 9:50
 */@Api(tags ="用户端控制器")@RestController@RequestMapping("/admin")publicclassAdminController{@ApiOperation(value ="获取数据")@GetMapping("/test")publicList<SwaggerUser>test(@ApiParam(name ="id",value ="用户Id")Long id,@ApiParam(name ="name",value ="用户名称")String name){List<SwaggerUser> list =newArrayList<>();
        list.add(SwaggerUser.builder().id(id).name(name).build());return list;}}

api

packagecom.eric.springbootknife4j.api;importcom.eric.springbootknife4j.entity.SwaggerUser;importio.swagger.annotations.Api;importio.swagger.annotations.ApiOperation;importio.swagger.annotations.ApiParam;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestMapping;importorg.springframework.web.bind.annotation.RestController;importjava.util.ArrayList;importjava.util.List;/**
 * @author Eric
 * @date 2023-07-31 9:50
 */@Api(tags ="用户端控制器")@RestController@RequestMapping("/api")publicclassApiController{@ApiOperation(value ="获取数据")@GetMapping("/test")publicList<SwaggerUser>test(@ApiParam(name ="id",value ="用户Id")Long id,@ApiParam(name ="name",value ="用户名称")String name){List<SwaggerUser> list =newArrayList<>();
        list.add(SwaggerUser.builder().id(id).name(name).build());return list;}}