Springboot使用Knife4j

你的名字 2023-09-27 12:32 124阅读 0赞

简述：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 分为多个版本 每个版本对应的依赖包不同，使用时请阅读官方文档，避免踩坑。

![e87c43b0b5e30dbb6b0dcd8ece8a94ca.png][]

项目工程截图：

![7e83c0b66ac27e1e1957086d200b1685.png][]

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() {
        }
        
    }

效果图：

![8e6bb7d4747178d6f8f7d554b49bb681.png][]

文档描述：

![d776336abfa68b2c6374a823a77d0b54.png][]

设置安全密码登录配置：

server.port=8081
    knife4j.enable=true
    knife4j.basic.enable=true
    knife4j.basic.username=admin
    knife4j.basic.password=admin
    knife4j.setting.language=zh-CN

登录界面：

![dec2511ef79db996dcaa89e17f028cce.png][]

[e87c43b0b5e30dbb6b0dcd8ece8a94ca.png]: https://img-blog.csdnimg.cn/img_convert/e87c43b0b5e30dbb6b0dcd8ece8a94ca.png
[7e83c0b66ac27e1e1957086d200b1685.png]: https://img-blog.csdnimg.cn/img_convert/7e83c0b66ac27e1e1957086d200b1685.png
[8e6bb7d4747178d6f8f7d554b49bb681.png]: https://img-blog.csdnimg.cn/img_convert/8e6bb7d4747178d6f8f7d554b49bb681.png
[d776336abfa68b2c6374a823a77d0b54.png]: https://img-blog.csdnimg.cn/img_convert/d776336abfa68b2c6374a823a77d0b54.png
[dec2511ef79db996dcaa89e17f028cce.png]: https://img-blog.csdnimg.cn/img_convert/dec2511ef79db996dcaa89e17f028cce.png