knife4j(Swagger2)使用

knife4j(Swagger2)使用

Scroll Down

knife4j(Swagger2)使用

快速使用

引入依赖(gradle)

implementation "com.github.xiaoymin:knife4j-spring-boot-starter:3.0.2"

开启Knife4j

@EnableSwagger2 //若使用 @EnableOpenApi 可以开启Swagger3, Knife4j是基于Swagger的
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

配置详解

基本配置

/**
 * 文档配置
 *
 * @author violetfreesia
 * @date 2021-02-22
 */
@Configuration	//这个别忘了,声明为配置类
@EnableSwagger2 //在这里开启了Swagger2, 启动类上就不用加了
@EnableKnife4j //这里开启的是Knife4j的增强模式
public class Knife4jConfig {
    @Bean(value = "api")
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
				//.enable(true) //可以选择是否开启文档
                .apiInfo(apiInfo())
                //分组名称
                .groupName("knif4j demo")
                // 选择哪些接口作为doc发布
                .select()
            // 这里是根据包名筛选,还可以选择其他方式,可查看RequestHandlerSelectors类
      .apis(RequestHandlerSelectors.basePackage("com.violetfreesia.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * api基本信息
     *
     * @return api基本信息对象
     */
    public ApiInfo apiInfo() {
        Contact contact = new Contact("violetfreesia",
                "violetfreesia.com", "violetfreesia@foxmail.com");
        return new ApiInfoBuilder()
                .title("TEST-API")
                .description("Knife4j Test")
                .termsOfServiceUrl("http://localhost:6969/test/doc.html")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

多分组配置

/**
 * 多分组配置, 配置多个Docket就行了
 *
 * @author violetfreesia
 * @date 2021-02-22
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Knife4jConfig {
    @Bean(value = "api")
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("knif4j demo group one")
                .select()
      .apis(RequestHandlerSelectors.basePackage("com.violetfreesia.controller.v1"))
                .paths(PathSelectors.any())
                .build();
    }
    
    @Bean(value = "api")
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("knif4j demo group two")
                .select()
      .apis(RequestHandlerSelectors.basePackage("com.violetfreesia.controller.v2"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * api基本信息
     *
     * @return api基本信息对象
     */
    public ApiInfo apiInfo() {
        Contact contact = new Contact("violetfreesia",
                "violetfreesia.com", "violetfreesia@foxmail.com");
        return new ApiInfoBuilder()
                .title("TEST-API")
                .description("Knife4j Test")
                .termsOfServiceUrl("http://localhost:6969/test/doc.html")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

开启认证

/**
 * 认证配置
 *
 * @author violetfreesia
 * @date 2021-02-22
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Knife4jConfig {
    @Bean(value = "api")
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("knif4j demo")
                .select()
      .apis(RequestHandlerSelectors.basePackage("com.violetfreesia.controller"))
                .paths(PathSelectors.any())
                .build()
            	// 在这里配置认证方式和应用范围
            	.securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }
    
    /**
     * 认证方式
     */
     private List<SecurityScheme> securitySchemes() {
         // 这里的认证方式根据实际需求变更
        ApiKey apiKey = new ApiKey("认证参数", HttpHeaders.AUTHORIZATION, In.HEADER.toValue());
        return Collections.singletonList(apiKey);
    }

    /**
     * 认证信息全局应用
     */
    private List<SecurityContext> securityContexts() {
        return Collections.singletonList(SecurityContext.builder()
                .securityReferences(Collections.singletonList(new SecurityReference("认证参数",
                        new AuthorizationScope[]{new AuthorizationScope("global", "")})))
                .build()
        );
    }

    public ApiInfo apiInfo() {
        Contact contact = new Contact("violetfreesia",
                "violetfreesia.com", "violetfreesia@foxmail.com");
        return new ApiInfoBuilder()
                .title("TEST-API")
                .description("Knife4j Test")
                .termsOfServiceUrl("http://localhost:6969/test/doc.html")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

全局参数类忽略

/**
 *  全局参数类忽略配置
 *
 * @author violetfreesia
 * @date 2021-02-22
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Knife4jConfig {
    @Bean(value = "api")
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("knif4j demo")
                .select()
      .apis(RequestHandlerSelectors.basePackage("com.violetfreesia.controller"))
                .paths(PathSelectors.any())
                .build()
            	// 在这里配置需要忽略的参数类就好了
            	.ignoredParameterTypes(Device.class);
    }

    public ApiInfo apiInfo() {
        Contact contact = new Contact("violetfreesia",
                "violetfreesia.com", "violetfreesia@foxmail.com");
        return new ApiInfoBuilder()
                .title("TEST-API")
                .description("Knife4j Test")
                .termsOfServiceUrl("http://localhost:6969/test/doc.html")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

如果需要在局部某个方法上忽略就使用@ApiIgnore注解要忽略的参数;

全局请求参数

/**
 *  全局请求参数配置
 *
 * @author violetfreesia
 * @date 2021-02-22
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Knife4jConfig {
    @Bean(value = "api")
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("knif4j demo")
                .select()
      .apis(RequestHandlerSelectors.basePackage("com.violetfreesia.controller"))
                .paths(PathSelectors.any())
                .build()
            	// 在这里配置全局请求参数
            	.globalRequestParameters(parameters());
    }
    
    private List<RequestParameter> parameters() {
        RequestParameterBuilder parameterBuilder = new RequestParameterBuilder();
        RequestParameter parameter = parameterBuilder.name("token")
                .in(ParameterType.HEADER)
                .description("认证token")
                .required(true)
                .build();
        return Collections.singletonList(parameter);
    }

    public ApiInfo apiInfo() {
        Contact contact = new Contact("violetfreesia",
                "violetfreesia.com", "violetfreesia@foxmail.com");
        return new ApiInfoBuilder()
                .title("TEST-API")
                .description("Knife4j Test")
                .termsOfServiceUrl("http://localhost:6969/test/doc.html")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

knife4j增强模式

这里是常用配置,详情见官网

knife4j:
  enable: true
  setting:
    enableSwaggerModels: true
    enableDocumentManage: true
    swaggerModelName: 实体类列表
    enableVersion: false
    enableFooter: false
  cors: false
  production: false