swagger接口文档 两款UI:SwaggerBootstrapUI 与 knife4j

参考：

swagger2：springboot + swagger2 + (SwaggerBootstrapUI | knife4j)
swagger3： springboot 2.7.x + swagger3

搭建接口文档技术栈：
springboot 2.7.x + swagger3 + knife4j
接口文档访问地址：

# 访问地址1： http://xxx:8080/swagger-ui/index.html
# 访问地址2： http://xxx:8080/doc.html

1.引入依赖 pom.xml

 <!--1. swagger3 核心-->
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-boot-starter</artifactId>
     <version>3.0.0</version>
 </dependency>
 <!--2. swagger3 的 knife4j UI美化（可选） -->
 <dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-spring-ui</artifactId>
     <version>3.0.3</version>
 </dependency>

2.添加配置类 SwaggerConfig.java

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.*;

@EnableOpenApi
@Configuration
public class SwaggerConfig {
    
    
    @Value("${swagger.enable}")
    private boolean enableSwagger;
    @Value("${swagger.contact.name}")
    private String contactName;
    @Value("${swagger.contact.url}")
    private String contactUrl;
    @Value("${swagger.contact.email}")
    private String contactEmail;
    @Value("${swagger.title}")
    private String title;
    @Value("${swagger.version}")
    private String version;
    @Value("${swagger.basePackage}")
    private String basePackage;
    @Value("${swagger.description}")
    private String description;

    @Bean
    public Docket createRestApi() {
    
    
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .groupName("Normal")
                .enable(enableSwagger)
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build()
                // 支持的通讯协议集合
                // .protocols(("https", "http"))
                .pathMapping("/")
                // 添加token认证请求配置，不需要可以注释掉以下两
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    private ApiInfo apiInfo() {
    
    
        return new ApiInfoBuilder()
                //标题
                .title(title)
                //简介
                .description(description)
                //服务条款
                .termsOfServiceUrl("")
                //协议
                .license("The Apache License")
                //作者个人信息
                .contact(new Contact(contactName, contactUrl, contactEmail))
                //版本
                .version(version)
                .build();
    }

    /**
     * 认证的安全上下文
     */
    private List<SecurityScheme> securitySchemes() {
    
    
        List<SecurityScheme> securitySchemes = new ArrayList<>();
        securitySchemes.add((SecurityScheme) new ApiKey("token", "token", "header"));
        return securitySchemes;
    }

    /**
     * 授权信息全局应用
     */
    private List<SecurityContext> securityContexts() {
    
    
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.any()).build());
        return securityContexts;
    }

    private List<SecurityReference> defaultAuth() {
    
    
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

}

3.添加spring boot 配置文件application.yml

### 【Swagger接口文档】
# 访问地址1： http://xxx:8080/swagger-ui/index.html
# 访问地址2： http://xxx:8080/doc.html
swagger:
  enable: true  #swagger接口网站开启配置
  basePackage: com.example.uaa #基础扫描包范围
  contact:
    name: aesop
    url: http://xxx.com
    email: [email protected]
  title: Swagger3.0.0 RESTful APIs 接口文档  #接口文档标题
  version: v1.1  #接口文档版本
  description: 接口文档查看和接口调试  #接口文档描述
  
spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher # 这个必须加，否则swagger3启动报错

需要注意的是，需要修改idea的配置文件编码为utf-8，以处理中文乱码问题，配置如下图所示：

4.启动

访问接口文档地址：http://xxx:8080/doc.html