Springboot使用Knife4j

     阅读:60

简述: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测试, 有需要的小伙伴可以自行下载,有问题可以及时评论,如没有积分的小伙伴评论提供邮箱地址 每天登录看到会后及时发送字,感谢各位。