SpringBoot集成Swagger3并配合knife4j增强文档

前提

1. knife4j自带swagger依赖，不需要再引入其他swagger依赖
2. 如果要使用 swagger-spring-boot-starter 依赖，则knife4j必须和swagger的版本相对应
3. 官方文档
4. 版本对应关系

1. 引入依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

<!--如果SpringBoot版本大于2.3则需要引入下面依赖-->
<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>2.0.1.Final</version>
</dependency>

2. 配置swagger3

import com.shop.common.constant.Constant;
import io.swagger.annotations.Api;
import lombok.SneakyThrows;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Response;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.net.InetAddress;
import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableOpenApi
@Slf4j
public class Swagger3Configuration {

    @Value("${spring.profiles.active:''}")
    private String active;
    @Value("${server.port}")
    private int port;
    @Value("${server.servlet.context-path:}")
    private String contextPath;

    @Bean
    @SneakyThrows
    public Docket shopManager() {
        Docket docket = new Docket(DocumentationType.OAS_30)
                // 非生产环境才开启swagger
                .enable(!active.equalsIgnoreCase(Constant.SPRING_PROFILES_ACTIVE_PRO))
                .groupName("group1")
                .apiInfo(apiInfo())
                // 设置自定义返回消息体
                .globalResponses(HttpMethod.GET, globalResponse())
                .globalResponses(HttpMethod.POST, globalResponse())
                .select()
                // 扫描带有@Api注解的类
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                // 扫描的基础路径 any()：任何请求都扫描；none()：任何请求都不扫描；ant("/manager")：扫描该路径下的请求
                .paths(PathSelectors.any())
                .build();

        String ipAddress = InetAddress.getLocalHost().getHostAddress();
        // 控制台输出Swagger3接口文档地址
        log.info("Swagger3接口文档地址: http://{}:{}{}/swagger-ui.html", ipAddress, port, contextPath);
        // 控制台输出Knife4j增强接口文档地址
        log.info("Knife4j增强接口文档地址: http://{}:{}{}/doc.html", ipAddress, port, contextPath);

        return docket;
    }


    private ApiInfo apiInfo(){
        String title = "XXX系统";
        String description = "API接口文档";
        String version = "1.0.0";
        String license = "";
        String termsOfServiceUrl = "";
        Contact contact = new Contact("乌兹，YYDS", "https://www.huya.com/uzi", "123456789@qq.com");
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .version(version)
                .license(license)
                .termsOfServiceUrl(termsOfServiceUrl)
                .contact(contact)
                .build();
    }

    private List<Response> globalResponse(){
        List<Response> responseList = new ArrayList<>();
        responseList.add(new ResponseBuilder().code("401").description("未认证").build());
        responseList.add(new ResponseBuilder().code("403").description("请求被禁止").build());
        responseList.add(new ResponseBuilder().code("404").description("找不到资源").build());
        return responseList;
    }

}

3. 启动类添加注解@EnableKnife4j

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@EnableKnife4j
public class Knife4jApplication {

    public static void main(String[] args) {
        SpringApplication.run(Knife4jApplication.class, args);
    }

}

4. Knife4j文档地址：

http://ip:port/doc.html

5. 增强配置

待补充

总结

swagger3 VS swagger2
swagger3 和swagger2 的区别主要体现在以下方面：

1. 启动 Swagger 的注解不同：swagger3使用的是 @EnableOpenApi，而swagger2是 @EnableSwagger2；
2. Docket（文档摘要信息）的文件类型配置不同：swagger3配置的是 OAS_3，而swagger2是 SWAGGER_2