SpringBoot集成增强版Swagger（Knife4j）

技术交流
, ,
1

SpringBoot集成增强版Swagger（Knife4j）

官网

Knife4j强大之处

  • 提供比bootstrap-ui更漂亮的UI界面

  • 集成方便，引入依赖少

  • 生产环境禁用配置knife4j.production=true

  • 支持Markdown/Html/Word/OpenAPI/PDF多种文档格式导出

引入依赖
<!--knife4j start-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.8</version>
</dependency>
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>20.0</version>
</dependency>
<!--knife4j end-->

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.16</version>
</dependency>
配置文件yaml
knife4j:
  # 开启增强配置，此配置可配置ignoreParameters忽略参数
  enable: true
  # 开启生产环境屏蔽
  production: false
  basic:
    enable: true
    # Basic认证用户名
    username: test
    # Basic认证密码
    password: 123
配置类
  • @EnableSwagger2WebMvc注解自动添加静态资源映射
package com.jonny.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import com.google.common.base.Function;
import com.google.common.base.Optional;
import com.google.common.collect.Lists;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.Parameter;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

import java.util.ArrayList;
import java.util.List;
import java.util.function.Predicate;

@Configuration
@EnableSwagger2WebMvc
@EnableKnife4j
public class Knife4jConfig {

    public final static String splitor = ";";

    @Bean
    public Docket openApi() {
        List<Parameter> parameters = getParameters();
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .globalOperationParameters(parameters)
                .select()
                .apis(basePackage("com.jonny.controller.api;com.jonny.controller"))
                .paths(PathSelectors.any())
                .build()
                .groupName("Open API")
                .securitySchemes(security());
    }

    @Bean
    public Docket manageApi() {
        List<Parameter> parameters = getParameters();
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .globalOperationParameters(parameters)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.jonny.system"))
                .paths(PathSelectors.ant("/manage/**"))
                .build()
                .groupName("后台管理")
                .securitySchemes(security());
    }

    /**
     *  全局请求头
     * @return
     */
    private List<Parameter> getParameters() {
        List<Parameter> parameters = new ArrayList<>();
        parameters.add(new ParameterBuilder()
                .name("Authorization")
                .description("token请求头：Bearer 44f0d54c-fc11-4743-88a8-f25ea5bd5f4a")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build());
        return parameters;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("后台管理系统")
                .version("1.0")
                .description("用户后台管理")
                .build();
    }

    private List<SecurityScheme> security() {
        return Lists.newArrayList(
                new ApiKey("Authorization", "Authorization", "header")
        );
    }

    public static Predicate<RequestHandler> basePackage(final String basePackage) {
        return input -> declaringClass(input).transform(handlerPackage(basePackage)).or(true);
    }

    private static Function<Class<?>, Boolean> handlerPackage(final String basePackage)     {
        return input -> {
            // 循环判断匹配
            for (String strPackage : basePackage.split(splitor)) {
                boolean isMatch = input.getPackage().getName().startsWith(strPackage);
                if (isMatch) {
                    return true;
                }
            }
            return false;
        };
    }

    private static Optional<? extends Class<?>> declaringClass(RequestHandler input) {
        return Optional.fromNullable(input.declaringClass());
    }
}
实体类
package com.jonny.domain;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;

@Data
@ApiModel("用户")
@AllArgsConstructor
public class User {

    @ApiModelProperty("用户名")
    private String username;

    @ApiModelProperty("密码")
    private String password;
}
控制器
package com.jonny.controller.system;

import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import com.github.xiaoymin.knife4j.annotations.ApiSupport;
import com.jonny.domain.User;
import com.jonny.domain.UserForm;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation("查询")
    @PostMapping("/get")
    public User list() {
        return new User("", "");
    }

    @ApiOperation("保存")
    @PostMapping("/save")
    @ApiOperationSupport(author = "张三", ignoreParameters = {"password1"})
    public User save(@RequestBody UserForm form) {
        System.out.println();
        return new User("", "");
    }

    @ApiOperation("更新")
    @PostMapping("/update")
    @ApiOperationSupport(author = "张三", ignoreParameters = {"password1"})
    public User update(UserForm form) {
        System.out.println();
        return new User("", "");
    }
}
启动后访问地址：http://localhost:port/doc.html

注意

  • @ApiOperationSupport(author = "张三", ignoreParameters = {"password1"})可以忽略指定属性，必须启用增强模式knife4j.enable=true

  • 如果用了knife4j的starter，其他swagger相关的依赖最好全部去掉，只是用starter，不然可能会冲突，也可以值引用knife4j的ui依赖，具体参照官网

  • 开发过程中踩到的坑，实体类的@ApiModel("")注解名称一定不要一样，不然可能会造成实体类属性修改了，界面上还没变的问题

  • ui首页刷新报错

    Illegal DefaultValue null for parameter type integer java.lang.NumberFormatException: For input string: “”

    该异常是由 swagger 引起的swagger 版本 1.9.2

    <!--  解决 Illegal DefaultValue null for parameter type integer    异常  -->
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.5.21</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.5.21</version>
</dependency>

  • 效果图

image
image1920×943 53.9 KB

image
image1920×943 46.4 KB

image
image1920×943 83.1 KB