Knife4j是什么?有什么作用?
Knife4j是一个基于Swagger的Java RESTful API文档工具,旨在帮助开发者轻松生成和维护API文档。它继承并增强了Swagger的功能,简化了使用流程,并提供了一系列增强功能,如接口文档的自动生成、可视化接口测试等
Knife4j的功能和特点
- 自动生成API文档:Knife4j可以根据Spring Boot项目中的接口注解和代码结构自动生成API文档,减少了手动编写文档的工作量3。
- 可视化接口测试:Knife4j集成了可交互式的接口调试功能,可以直接在文档页面上测试接口并查看返回结果,方便开发人员进行接口调试和验证3。
- 增量更新:支持增量更新,无需整个项目重启即可更新文档,提高了开发效率2。
- 高度定制化:Knife4j提供了丰富的配置选项和插件,可以满足多种需求,并且界面美观、使用流畅13。
- 兼容性:几乎可以无缝对接所有主流的Java MVC框架,如Spring MVC、Struts2等
使用方式
1.导入坐标
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi2-spring-boot-starter</artifactId><version>4.0.0</version></dependency>
2.添加配置类
package com.ktjy.shiro1.config;import io.swagger.annotations.ApiOperation; 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;import java.util.logging.Level; import java.util.logging.Logger;/*** Swagger配置类,用于创建和配置Swagger接口文档*/ @Configuration @EnableSwagger2WebMvc public class SwaggerConfig {private static final Logger logger = Logger.getLogger(SwaggerConfig.class.getName());/*** 创建Docket存入容器,Docket代表一个接口文档** @return Docket实例,配置了接口文档的具体信息和选择器*/@Bean(value = "defaultApi")public Docket webApiConfig() {try {return new Docket(DocumentationType.SWAGGER_2)// 指定组名.groupName("Swagger")// 创建接口文档的具体信息.apiInfo(webApiInfo())// 创建选择器,控制哪些接口被加入文档.select()// 指定@ApiOperation标注的接口被加入文档.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 指定包名并且带有RestController或者Controller注解/* .apis(RequestHandlerSelectors.basePackage("com.ktjy.shiro1.contorller").and(RequestHandlerSelectors.withClassAnnotation(RestController.class).or(RequestHandlerSelectors.withClassAnnotation(Controller.class))))*/// 所有路径都被加入文档.paths(PathSelectors.any()).build();} catch (Exception e) {logger.log(Level.SEVERE, "Failed to create Docket for Swagger", e);throw new RuntimeException("Failed to create Docket for Swagger", e);}}/*** 创建接口文档的具体信息,会显示在接口文档页面中** @return ApiInfo实例,包含了文档的标题、描述、版本、联系人信息等*/private ApiInfo webApiInfo() {try {return new ApiInfoBuilder()// 文档标题.title("文档标题")// 文档描述.description("文档描述")// 版本.version("1.0")// 联系人信息.contact(new Contact("汤汤", "无", "1241435267@qq.com"))// 版权.license("汤汤归属")// 版权地址.licenseUrl("无").build();} catch (Exception e) {logger.log(Level.SEVERE, "Failed to create ApiInfo for Swagger", e);throw new RuntimeException("Failed to create ApiInfo for Swagger", e);}} }
常用注解和必须事项
配置类进行了配置,只有添加了ApiOperation注解的controller才会被读取到
注解 作用范围 @Api(tags = "用户登录") 添加在controller类上,标明该类作用 @ApiOperation(value = "校验登录") 添加在controller方法上,标明方法作用 @ApiParam(value = "登录信息", required = true ) LoginVo loginVo 添加在controller方法的参数列表中,如果参数是类,则可以读取到类中的注解信息,不可以代替
RequestParam注解,有默认值要求需要全部添加@ApiModel(value = "登录参数") 声明一个Vo类 @ApiModelProperty(value = "密码",required = true) 标明Vo类中的参数
controller方法参数列表
@ApiOperation(value = "校验登录")@RequestMapping(value = "/dologin")public String doLogin(@ApiParam(value = "登录信息", required = true ) LoginVo loginVo,Model model, HttpSession session)
登录的Vo类
@Data @ApiModel(value = "登录参数") public class LoginVo {@ApiModelProperty(value = "用户名",required = true)private String usrName;@ApiModelProperty(value = "密码",required = true)private String usrPassword; }
swaggerApi的显示效果