SpringBoot项目里如何实现 Knife4J 的集成与配置？

本文共计1476个文字，预计阅读时间需要6分钟。

目录

一、引入依赖

二、创建配置类

三、常用注解

3-1 @Api 3-1-1 @Api的常用属性 3-1-2 @Api的不常用属性

四、@ApiOperation

4-1 @ApiOperation的常用属性

目录

• 一、引入依赖
• 二、创建配置类
• 三、常用注解
• 3-1 @Api
• 3-1-1 @Api 注解的常用属性，如下：
• 3-1-2 @Api 注解的不常用属性，如下：
• 3-2 @ApiOperation
• 3-2-1 @ApiOperation 注解的常用属性，如下：
• 3-2-2 @ApiOperation 注解的不常用属性，如下：
• 3-3 @ApiImplicitParam
• 3-3-1 @ApiImplicitParam 注解的常用属性，如下：
• 3-3-2 @ApiImplicitParam 注解的不常用属性，如下：
• 3-4 @ApiModel
• 3-4-1 @ApiModel 注解的常用属性，如下：
• 3-5 @ApiModelProperty
• 3-5-1 @ApiModelProperty 注解的常用属性，如下：
• 3-5-2 @ApiModelProperty 注解的不常用属性，如下：
• 3-6 @ApiResponse
• 四、配置JavaBean
• 五、配置Controller
• 六、接口文档预览

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

knife4j的前身是swagger-bootstrap-ui，为了契合微服务的架构发展，由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿，因此项目正式更名为knife4j。 knife4j官方网址：knife4j

一、引入依赖

Knife4J 官网：

doc.xiaominfo.com/

快速开始：doc.xiaominfo.com/docs/quick-start

<!--引入Knife4j的官方start包,Swagger2基于Springfox2.10.5项目--> <dependency> <groupId>com.github.xiaoymin</groupId> <!--使用Swagger2--> <artifactId>knife4j-spring-boot-starter</artifactId> <version>2.0.9</version> </dependency>

二、创建配置类

创建config包，在其中新建一个配置类：

@Configuration @EnableSwagger2WebMvc public class Knife4jConfiguration { @Bean(value = "dockerBean") public Docket dockerBean() { //指定使用Swagger2规范 Docket docket=new Docket(DocumentationType.SWAGGER_2) .apiInfo(new ApiInfoBuilder() //描述字段支持Markdown语法 .description("# 写一个简要的描述") .termsOfServiceUrl("doc.xiaominfo.com/") .contact("可以写作者的信息") .version("1.0") .build()) //分组名称 .groupName("用户服务") .select() //这里指定Controller扫描包路径 .apis(RequestHandlerSelectors.basePackage("com.xueou.boot.controller")) .paths(PathSelectors.any()) .build(); return docket; } }

• 最重要的配置还是：指定
• Controller扫描包路径contact

官方是弃用了直接传字符串的这个设置方法，改用传入一个Contact类，看一下源码可以发现该类的结构（内容更丰富了：姓名、邮箱、URL连接）

三、常用注解

3-1 @Api

@Api 注解，添加在 Controller 类上，标记它作为 Swagger 文档资源。

3-1-1 @Api 注解的常用属性，如下：

• tags 属性：用于控制 API 所属的标签列表。[] 数组，可以填写多个。
• 可以在一个 Controller 上的 @Api 的 tags 属性，设置多个标签，那么这个 Controller 下的 API 接口，就会出现在这两个标签中。
• 如果在多个 Controller 上的 @Api 的 tags 属性，设置一个标签，那么这些 Controller 下的 API 接口，仅会出现在这一个标签中。
• 本质上，tags 就是为了分组 API 接口，和 Controller 本质上是一个目的。所以绝大数场景下，我们只会给一个 Controller 一个唯一的标签。

3-1-2 @Api 注解的不常用属性，如下：

• produces 属性：请求请求头的可接受类型( Accept )。如果有多个，使用 , 分隔。
• consumes 属性：请求请求头的提交内容类型( Content-Type )。如果有多个，使用 , 分隔。
• protocols 属性：协议，可选值为 “xxx/xxx.png") private String imgUrl; @ApiModelProperty(value = "标题", example = "这是一个标题哟~") private String title; }

  我自己用的时候，又封装了一层，设置了几个JavaBean用于包装返回的响应结果：

  分别用于返回单个数据、数据列表，同时附带上状态码和说明信息。

  @Data @ToString @AllArgsConstructor @NoArgsConstructor public abstract class RBean { @ApiModelProperty(value = "响应码", position = 0, example = "200", notes = "200: 成功；500：失败；") private Integer code; @ApiModelProperty(value = "响应说明", position = 1, example = "xx数据获取成功。") private String msg; } // ===================== @EqualsAndHashCode(callSuper=true) @Data @ToString @AllArgsConstructor @NoArgsConstructor public class ROneBean<T> extends RBean { @ApiModelProperty(value = "数据项", position = 2) private T data; } // ======================= @EqualsAndHashCode(callSuper=true) @Data @ToString @AllArgsConstructor @NoArgsConstructor public class RListBean<T> extends RBean{ @ApiModelProperty(value = "数据列表", position = 2) private List<T> data; }

  五、配置Controller

  潦草的写几个接口

  @Api(tags = "首页模块") @RestController public class IndexController { @Resource IBannerService iBannerService; @ApiOperation(value = "域名直接转接口文档", hidden = true) @GetMapping("/") public void toDoc(HttpServletResponse response) throws IOException { response.sendRedirect("/doc.html"); } @ApiOperation("新增轮播图数据") @PostMapping("/addBanners") public void putBanner(@RequestBody Banner banner){ // ...... } @ApiOperation("查询一个具体轮播图") @ApiImplicitParams({ @ApiImplicitParam(name = "title",value = "标题",required = true,example = "小白菜"), @ApiImplicitParam(name = "date",value = "时间",required = true,example = "2022") }) @GetMapping("/searchOneBanner") public ROneBean<Banner> searchOneBanner(@RequestParam(name = "title",defaultValue = "") String name, @RequestParam(name = "date", defaultValue = "") String address){ ROneBean<Banner> resp = new ROneBean<>(); // ... return null } @ApiOperation("获取轮播图数据") @GetMapping("/getBanners") public RListBean<Banner> getBanners(){ RListBean<Banner> resp = new RListBean<>(); List<Banner> banners = iBannerService.list(); if(banners.isEmpty()){ resp.setCode(200); resp.setMsg("轮播图数据为空。"); }else{ resp.setCode(200); resp.setMsg("获取轮播图数据成功"); resp.setData(banners); } return resp; } }

  六、接口文档预览

  到此这篇关于SpringBoot中使用Knife4J的文章就介绍到这了,更多相关SpringBoot使用Knife4J内容请搜索自由互联以前的文章或继续浏览下面的相关文章希望大家以后多多支持自由互联！