<!-- Spring Boot 項(xiàng)目starter,快速使用knife4j增強(qiáng)文檔 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-spring-boot-starter</artifactId>
	<version>3.0.3</version>
</dependency>

package com.dake.common.config;
 
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.jetbrains.annotations.NotNull;
import org.springframework.beans.BeansException;
import org.springframework.beans.factory.config.BeanPostProcessor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import org.springframework.util.ReflectionUtils;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping;
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.spring.web.plugins.WebFluxRequestHandlerProvider;
import springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
import java.lang.reflect.Field;
import java.util.List;
import java.util.stream.Collectors;
 
/**
 * Knife4j 3.X 配置類.
 * 訪問(wèn)地址：
 * <p>
 *     Knife4j 訪問(wèn)首頁(yè)：<a href="http://localhost:8090/doc.html#/home">...</a>
 * </p>
 *
 * @author fangqi
 * @date 2022-6-27 23:43:39
 */
@EnableKnife4j
@Configuration
@EnableSwagger2
@Import(BeanValidatorPluginsConfiguration.class)
// 在 Swagger 3.X 以下版本報(bào)錯(cuò)時(shí)可以加此注解解決，但是在3.X版本以上的，加此注解會(huì)導(dǎo)致頁(yè)面無(wú)法打開(kāi)
//@EnableWebMvc
public class SwaggerConfig {
 
    private static final String SWAGGER_TITLE = "XXX項(xiàng)目 API 接口文檔";
    private static final String VERSION = "3.0.3";
 
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .enable(true)
                // .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .groupName("3.X 版本")
                .select()
                // 方式一: 配置掃描 所有想在swagger界面的統(tǒng)一管理接口，都必須在此包下
//                .apis(RequestHandlerSelectors.basePackage("com.dake.controller"))
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                // 方式二: 只有當(dāng)方法上有  @ApiOperation 注解時(shí)才能生成對(duì)應(yīng)的接口文檔
                // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(SwaggerConfig.SWAGGER_TITLE)
                .description("# XXX項(xiàng)目API接口文檔簡(jiǎn)介")
                .termsOfServiceUrl("http://127.0.0.1/#/login")
                .contact(new Contact("fangqi", "", "fang_qi170@126.com"))
                .version(SwaggerConfig.VERSION)
                .build();
    }
 
    @Bean
    public static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {
        return new BeanPostProcessor() {
            @Override
            public Object postProcessAfterInitialization(@NotNull Object bean, @NotNull String beanName) throws BeansException {
                if (bean instanceof WebMvcRequestHandlerProvider || bean instanceof WebFluxRequestHandlerProvider) {
                    customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
                }
                return bean;
            }
 
            private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings(List<T> mappings) {
                List<T> copy = mappings.stream()
                        .filter(mapping -> mapping.getPatternParser() == null)
                        .collect(Collectors.toList());
                mappings.clear();
                mappings.addAll(copy);
            }
 
            @SuppressWarnings("unchecked")
            private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) {
                try {
                    Field field = ReflectionUtils.findField(bean.getClass(),             "handlerMappings");
                    assert field != null;
                    field.setAccessible(true);
                    return (List<RequestMappingInfoHandlerMapping>) field.get(bean);
                } catch (IllegalArgumentException | IllegalAccessException e) {
                    throw new IllegalStateException(e);
                }
            }
        };
    }
 
}

springfox:
  documentation:
    swagger:
      v2:
        path: /api-docs
        use-model-v3: true
 
knife4j:
  # 開(kāi)啟增強(qiáng)
  enable: true
  # 開(kāi)啟登錄認(rèn)證
  basic:
    enable: true
    username: admin
    password: 123456

@Api(tags = "XX管理")
@ApiSupport(author = "fangqi", order = 1)

@ApiOperationSupport(author = "fangdake")

@ApiOperation(value = "查詢初始化數(shù)據(jù)", 
notes = "新增和修改頁(yè)面的初始化下拉列表數(shù)據(jù)", 
tags = "延伸操作")

@Data
@ApiModel(description = "查詢xxx列表DTO")
public class QueryBiListDTO {
 
    @NotBlank(message = "頁(yè)碼不能為空")
    @ApiModelProperty(value = "頁(yè)碼", required = true)
    private Integer pageNo;
 
    @NotBlank(message = "每頁(yè)條數(shù)不能為空")
    @ApiModelProperty(value = "每頁(yè)條數(shù)", required = true)
    private Integer pageCount;
 
    @ApiModelProperty(value = "xxid")
    private String id;
}

@ApiOperation("修改密碼")
    @ApiImplicitParams({
	@ApiImplicitParam(name = "username",value = "賬號(hào)" , dataType = "String", paramType = "query"),		
	@ApiImplicitParam(name = "oldPassword",value = "舊密碼" , dataType = "String", paramType = "query"),
	@ApiImplicitParam(name = "newPassword",value = "新密碼" , dataType = "String", paramType = "query")
	})

@PostMapping("addUser")
@ApiOperation("新增用戶")
@ApiOperationSupport(ignoreParameters = "id") // 忽略掉User中的id屬性，不顯示在文檔中
public void addUser(User user) {
 
}

@PostMapping("addUser2")
@ApiOperation("添加用戶2")
@ApiOperationSupport(ignoreParameters = {"user.id", "user.age"})
public void addUser2(@RequestBody User user) {
 
}