Spring Boot 启用 OpenAPI Swagger 访问

介绍

OpenAPI 是一个用于构建、维护和可视化 RESTful API 的开源框架。它可以帮助开发者在项目中创建规范的 API 文档，并且提供交互式的 API 测试和探索功能。

Swagger 是 OpenAPI 的一个实现，它提供了一套工具和规范，用于描述和定义 RESTful API。Spring Boot 是一个用于构建基于 Java 的快速开发框架，可以很方便地集成 Swagger 来生成和访问 API 文档。

本文将介绍如何在 Spring Boot 项目中启用 OpenAPI Swagger 访问，并提供详细的步骤和示例代码。

步骤

1. 添加 Swagger 相关依赖

在项目的 pom.xml 文件中，添加以下 Maven 依赖：

<dependencies>
    <!-- Spring Boot Starter Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Swagger 相关依赖 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
</dependencies>

2. 配置 Swagger 相关 Bean

在项目的配置文件中，添加以下配置：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

其中，RequestHandlerSelectors.basePackage 指定了 Controller 类所在的包路径，PathSelectors.any() 表示所有的 API 都会被文档化。

3. 启动应用程序

启动 Spring Boot 应用程序后，在浏览器中访问 http://localhost:8080/swagger-ui.html，即可看到生成的 API 文档界面。

4. 文档的其他自定义配置

如果需要对 API 文档进行进一步的自定义配置，可以在 SwaggerConfig 类中添加更多的配置方法。例如，可以通过 apiInfo() 方法来设置文档的标题、描述等信息：

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
}

private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("API 文档")
            .description("这是一个演示 Spring Boot 启用 Swagger 的 API 文档")
            .version("1.0.0")
            .build();
}

这里使用了 ApiInfoBuilder 类来设置文档的标题、描述和版本信息。

结论

通过配置和集成 Swagger，我们可以轻松地在 Spring Boot 项目中生成和访问 API 文档。Swagger 提供了良好的可视化界面和强大的功能，可以帮助开发者更好地管理和测试 RESTful API。

以上就是启用 OpenAPI Swagger 访问的步骤和示例代码。希望对程序员能提供丰富的信息，帮助大家在实际开发中更好地使用 Swagger。