SpringBoot Knife4j框架&Knife4j的显示内容的配置方式
作者:万物更新_
Knife4j框架是基于Swagger2开发的在线API文档生成工具,主要功能包括自动生成API文档、接口文档展示、接口测试工具、接口权限控制和在线调试,该框架支持通过注解自动生成详细的接口文档,开发者可以直接在文档界面进行接口测试和调试
Knife4j框架
Knife4j框架是一款国人开发的、基于Swagger 2的在线API文档框架。
Knife4j框架的一些主要作用和特点:
- 自动生成API文档:Knife4j可以根据代码中的注解和配置信息,自动生成API接口文档。开发者只需要在代码中添加相关注解,就能够生成详细的API文档,包括接口描述、请求参数、响应结果等信息。
- 接口文档展示:Knife4j生成的API文档以用户友好的方式展示,包括接口列表、接口详情、请求示例、参数说明等。开发者可以通过浏览器访问API文档,方便查阅和理解接口的使用方式。
- 接口测试工具:Knife4j提供了接口测试工具,可以直接在文档界面进行接口测试,无需额外的接口测试工具。开发者可以通过输入参数、发送请求,并查看响应结果,方便调试和验证接口的正确性。
- 接口权限控制:Knife4j支持对API接口进行权限控制,可以配置接口的访问权限,限制某些接口只能被特定的角色或用户访问。
- 接口在线调试:Knife4j提供了在线调试功能,可以在文档界面直接发送请求并查看响应结果,方便开发者进行接口的调试和验证。
使用
Knife4j的简单使用只需要3步:
添加依赖:
knife4j-spring-boot-starter
,版本2.0.9
注意:建议使用Spring Boot 2.5.x版本,如果使用更高版的Spring Boot,Knife4j的版本也需要提高
<knife4j-spring-boot.version>2.0.9</knife4j-spring-boot.version>
<!-- Knife4j Spring Boot:在线API文档 --> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>${knife4j-spring-boot.version}</version> </dependency>
添加配置:
在配置文件中添加knife4j.enable
属性的配置,取值为true
添加配置类:类的代码相对固定
检查配置Controller包的属性值是否与你的项目相符合
package cn.tedu.csmall.product.config; import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver; import lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; 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.EnableSwagger2WebMvc; /** * Knife4j配置类 * * @author java@tedu.cn * @version 0.0.1 */ @Slf4j @Configuration @EnableSwagger2WebMvc public class Knife4jConfiguration { /** * 【重要】指定Controller包路径 */ private String basePackage = "cn.tedu.csmall.product.controller"; /** * 分组名称 */ private String groupName = "product"; /** * 主机名 */ private String host = "http://java.tedu.cn"; /** * 标题 */ private String title = "酷鲨商城在线API文档--商品管理"; /** * 简介 */ private String description = "酷鲨商城在线API文档--商品管理"; /** * 服务条款URL */ private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0"; /** * 联系人 */ private String contactName = "Java教学研发部"; /** * 联系网址 */ private String contactUrl = "http://java.tedu.cn"; /** * 联系邮箱 */ private String contactEmail = "java@tedu.cn"; /** * 版本号 */ private String version = "1.0.0"; @Autowired private OpenApiExtensionResolver openApiExtensionResolver; public Knife4jConfiguration() { log.debug("创建配置类对象:Knife4jConfiguration"); } @Bean public Docket docket() { String groupName = "1.0.0"; Docket docket = new Docket(DocumentationType.SWAGGER_2) .host(host) .apiInfo(apiInfo()) .groupName(groupName) .select() .apis(RequestHandlerSelectors.basePackage(basePackage)) .paths(PathSelectors.any()) .build() .extensions(openApiExtensionResolver.buildExtensions(groupName)); return docket; } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title(title) .description(description) .termsOfServiceUrl(termsOfServiceUrl) .contact(new Contact(contactName, contactUrl, contactEmail)) .version(version) .build(); } }
完成后,可以通过 /doc.html
来访问API文档,即在浏览器的地址栏中输入网址:http://localhost:8080/doc.html
访问
Knife4j的显示内容的配置
@Api
:添加在控制器类上,通过此注解的tags
属性,可以配置模块名称(显示在API文档左侧目录中的名称)
提示:当存在多个控制器时,显示的顺序是根据配置的模块名称来决定的,如果需要自行指定顺序,建议在各模块名称前添加数字编号
例如:
@RestController @RequestMapping("/album") @Api(tags = "04. 相册管理模块") public class AlbumController { }
@ApiOperation
:添加在处理请求的方法上,通过此注解的value
属性,可以配置业务功能名称@ApiOperationSupport
:添加在处理请求的方法上,通过此注解的order
属性(int
类型),可以配置业务功能的排序序号,将升序排列
例如:
@PostMapping("/delete") @ApiOperation("根据ID删除相册") @ApiOperationSupport(order = 200) public String delete() { // ... }
@ApiModelProperty
:添加在封装的请求参数的属性上,通过此注解的value
属性,可以配置请求参数的描述信息,通过此注解的required
属性,可以配置是否必须提交此参数(此配置只是一种显示效果,并不具备真正的检查功能),通过此注解的example
属性,可以配置示例值,(示例值不是说明是举例,要满足属性类型,如果在排序Integer 输入字符串会报错)例如:
@Data public class AlbumAddNewParam implements Serializable { @ApiModelProperty(value = "相册名称", required = true, example = "可乐的相册") private String name; @ApiModelProperty(value = "相册简介", required = true, example = "可乐的相册的简介") private String description; @ApiModelProperty(value = "排序序号,必须是1~255之间的数字", required = true, example = "97") private Integer sort; }
@ApiIgnore
:添加在请求参数上,表示API文档将忽略此请求参数
@PostMapping("/add-new") @ApiOperation("添加相册") @ApiOperationSupport(order = 100) public String addNew(AlbumAddNewParam albumAddNewParam, @ApiIgnore HttpSession session) { // ... }
@ApiImplicitParam
:添加在处理请求的方法上,用于对未封装的请求参数进行描述,注意,此注解必须配置name
属性,取值为方法的参数名,然后,结合此注解的value
属性对参数进行描述,此注解还有与@ApiModelProperty
相同的一些属性,例如required
、example
等,还可以通过dataType
指定数据类型@ApiImplicitParams
:添加在处理请求的方法上,当有多个@ApiImplictParam
需要被配置时,应该将它们作为当前@ApiImplicitParams
的属性值
例如:
@PostMapping("/delete") @ApiOperation("根据ID删除相册") @ApiOperationSupport(order = 200) @ApiImplicitParams({ @ApiImplicitParam(name = "albumId", value = "相册ID", required = true, dataType = "long"), @ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "long") }) public String delete(Long albumId, Long userId) { // ... }
总结
以上为个人经验,希望能给大家一个参考,也希望大家多多支持脚本之家。