简述:knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。
knife4j的前身是 swagger-bootstrap-ui
,为了契合微服务的架构发展,由于原来 swagger-bootstrap-ui
采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j。
knife4j
knife4j官方网址:
搭建环境:java-8 、springboot 2.5.10、Gradle 7.4
推荐意见:使用插件其目的是为了简化内部对接,便利测试和前端调试,以及简化的解决程序员编写文档,在本地环境和测试环境可以使用,考虑到安全问题不要暴露在正式环境。
Knife4j 分为多个版本 每个版本对应的依赖包不同,使用时请阅读官方文档,避免踩坑。
项目工程截图:
Gradle配置:
plugins {
id 'org.springframework.boot' version '2.5.10'
id 'io.spring.dependency-management' version '1.0.11.RELEASE'
id 'java'
}
group = 'com.demo'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '1.8'
repositories {
mavenCentral()
}
ext {
lombokVersion = '1.16.18'
}
dependencies {
implementation 'org.springframework.boot:spring-boot-starter'
implementation 'org.springframework.boot:spring-boot-starter-web'
// knife4j
implementation group: 'com.github.xiaoymin', name: 'knife4j-spring-boot-starter', version: '3.0.3'
testImplementation 'org.springframework.boot:spring-boot-starter-test'
//lombok
implementation("org.projectlombok:lombok:$lombokVersion")
compileOnly("org.projectlombok:lombok:$lombokVersion")
annotationProcessor("org.projectlombok:lombok:$lombokVersion")
}
tasks.named('test') {
useJUnitPlatform()
}
springboot 配置knife4j:
package com.demo.config;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
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.EnableSwagger2;
@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class Knife4jConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.useDefaultResponseMessages(false)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.description("接口测试文档")
.contact(new Contact("beyourself", "https://blog.csdn.net/qq_27535933", "310857864@qq.com"))
.version("v1.0")
.title("API测试文档")
.build();
}
}
测试demo:
package com.demo.controller;
import com.demo.service.request.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
@RestController
@Api(tags = "用户接口")//描述UserController的信息
public class UserController {
@ApiOperation(value = "查询用户", notes = "根据id查询用户")
@ApiImplicitParam(paramType = "path", name = "id", value = "用户id", required = true)
@GetMapping("/user/query/{userId}")
public String getUserById(@PathVariable Integer userId) {
return "/user/" + userId;
}
@ApiResponses({
@ApiResponse(code = 200, message = "删除成功"),
@ApiResponse(code = 500, message = "删除失败")})
@ApiOperation(value = "删除用户", notes = "根据id删除用户")
@DeleteMapping("/user/delete/{id}")
public Integer deleteUserById(@PathVariable Integer id) {
return id;
}
@ApiOperation(value = "添加用户", notes = "添加一个用户,传入用户名和性别")
@ApiImplicitParams({
@ApiImplicitParam(paramType = "query", name = "username", value = "用户名", required = true, defaultValue = "张三"),
@ApiImplicitParam(paramType = "query", name = "sex", value = "性别", required = true, defaultValue = "女")
})
@PostMapping("/user")
public String addUser(@RequestParam String username, @RequestParam String sex) {
return username + "," + sex;
}
@ApiOperation(value = "修改用户", notes = "根据传入的用户信息修改用户")
@PutMapping("/user")
public String updateUser(@RequestBody User user) {
return user.toString();
}
@GetMapping("/ignore")
@ApiIgnore
public void ignoreMethod() {
}
}
效果图:
文档描述:
设置安全密码登录配置:
server.port=8081
knife4j.enable=true
knife4j.basic.enable=true
knife4j.basic.username=admin
knife4j.basic.password=admin
knife4j.setting.language=zh-CN
登录界面:
赚点积分下载地址: Springboot使用Knife4j-Java文档类资源-CSDN下载
已放在资源上用于做demo测试, 有需要的小伙伴可以自行下载,有问题可以及时评论,如没有积分的小伙伴评论提供邮箱地址 每天登录看到会后及时发送字,感谢各位。