SpringBoot整合knife4j(快速入门超详细版)
😊 @ 作者: 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
这就是首页
包括也是按照我们的配置文件来分组显示了,这里可根据自己项目的实际情况,按照微服务来分、按照功能目录来分都是可以的
如下就是我们的实体类,发现我们写的注释也都自动生成了
下面就是我们的接口调试界面了
自带路径、接口说明、参数说明,只要我们写了解释,这里都会显示
此时我们也可以点击调试,然后点击发送,就能看到我们的返回信息了,并且如果我们的返回实体类上有注解注释的,这里也是会显示的
总结
怎么样,是不是特别的方便和简单~