springboot整合swagger3

一、导入swagger3的依赖

	  <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

注意，如果你还需要页面更加美观，则再添加依赖。

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

二、SwaggerConfig代码的解读

让我逐行解释每一行代码的含义：

@Configuration
@EnableOpenApi
public class SwaggerConfig {

这是一个配置类的声明，使用了 @Configuration 注解，表示这是一个配置类。@EnableOpenApi 注解用于启用 Swagger 支持。

private static final String AUTHORIZATION_HEADER = "Authorization";
private static final String TOKEN_PREFIX = "Bearer ";

定义了两个常量，AUTHORIZATION_HEADER 用于定义认证头的名称，TOKEN_PREFIX 用于定义 Token 的前缀。

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_3)
            .apiInfo(apiInfo())
            .securitySchemes(Collections.singletonList(apiKey()))
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.minster.yanapi.controller"))
            .paths(PathSelectors.any())
            .build();
}

@Bean 注解表示该方法返回一个 Spring Bean，用于配置 Swagger 的 Docket 对象。

Docket 是 Swagger 的主要配置类，它提供了一系列的配置选项。在这个方法中，我们创建了一个 Docket 对象，并进行了以下配置：

• DocumentationType.SWAGGER_2：指定使用 Swagger 2 版本的规范。
• apiInfo(apiInfo())：设置 API 文档的基本信息，包括标题、描述、版本等。apiInfo() 方法返回一个 ApiInfo 对象，其中定义了这些基本信息。
• securitySchemes(Collections.singletonList(apiKey()))：配置接口的认证方式。这里使用了一个 API Key 认证方式，通过 apiKey() 方法返回一个 SecurityScheme 对象。
• select()：开始定义哪些接口要生成文档。下面的方法链指定了需要扫描的包路径。
• apis(RequestHandlerSelectors.basePackage("com.minster.yanapi.controller"))：扫描指定包路径下的接口。
• paths(PathSelectors.any())：扫描所有路径的接口。
• build()：构建 Docket 对象。

private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("API 文档标题")
            .description("API 文档描述")
            .version("1.0.0")
            .contact(new Contact("Your Name", "https://your-website.com", "your-email@example.com"))
            .build();
}

apiInfo() 方法返回一个 ApiInfo 对象，用于设置 API 文档的基本信息，包括标题、描述、版本和联系人等。

private SecurityScheme apiKey() {
    return new ApiKey(AUTHORIZATION_HEADER, AUTHORIZATION_HEADER, "header");
}

apiKey() 方法返回一个 SecurityScheme 对象，用于配置接口的认证方式。在这里，我们使用 API Key 的方式进行认证，并通过 AUTHORIZATION_HEADER 常量设置认证头的名称。

通过以上配置，SwaggerConfig 类定义了 Swagger 的基本配置和 API 文档信息，使得你可以生成并展示美观的接口文档界面。

三、整体代码

@Configuration
@EnableOpenApi
public class SwaggerConfig {

    // 定义全局的 token
    private static final String AUTHORIZATION_HEADER = "Authorization";
    private static final String TOKEN_PREFIX = "Bearer ";

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .securitySchemes(Collections.singletonList(apiKey()))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.minster.yanapi.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API 文档标题")
                .description("API 文档描述")
                .version("1.0.0")
                .contact(new Contact("Your Name", "https://your-website.com", "your-email@example.com"))
                .build();
    }

    private SecurityScheme apiKey() {
        return new ApiKey(AUTHORIZATION_HEADER, AUTHORIZATION_HEADER, "header");
    }
}

四、访问swagger3

访问地址：http://localhost:8080/swagger-ui/index.html

注意，swagger的端口应与springboot的端口一致，不然无法访问。