大公开，刚会Spring Boot3，就轻松搞定Swagger3

2023-11-29 18:31:05

在Spring Boot 3中无缝集成Swagger 3：详细指南

摘要

Spring Boot 3和Swagger 3是现代互联网开发中不可或缺的工具，它们分别简化了应用程序的构建和API文档的生成。本文将深入探讨如何在Spring Boot 3中集成Swagger 3，指导您轻松创建全面且用户友好的API文档。

1. 设置pom.xml

首先，我们需要在项目的pom.xml文件中添加Swagger 3的依赖项。这将允许我们使用Swagger 3库并将其与我们的应用程序集成。

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>swagger-bootstrap-ui</artifactId>
  <version>1.9.5</version>
</dependency>
<dependency>
  <groupId>cn.hutool</groupId>
  <artifactId>hutool-core</artifactId>
  <version>5.7.3</version>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
</dependency>

2. 创建SwaggerConfig类

接下来，我们需要创建SwaggerConfig类。此类负责配置Swagger 3设置并启动API文档的生成。

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API 文档")
                .description("API 文档")
                .version("1.0")
                .build();
    }
}

3. 修改DemoApplication类

现在，我们需要修改DemoApplication类。此类是应用程序的入口点，我们需要确保Swagger 3集成得到正确初始化。

@SpringBootApplication
public class DemoApplication {

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

4. 在控制器中添加注释

要生成有关应用程序控制器的API文档，我们需要在控制器中添加OpenAPI注解。这些注解提供有关API端点的元数据信息，例如它们的、参数和响应。

@RestController
@RequestMapping("/api")
public class ApiController {

    @ApiOperation(value = "获取用户信息")
    @GetMapping("/user")
    public User getUser() {
        return new User("张三", 18);
    }
}

5. 访问API文档

一旦我们完成所有配置和注解，就可以在浏览器中访问API文档。只需输入以下网址：

http://localhost:8080/swagger-ui.html

操作结果

现在，您将看到一个交互式的API文档，其中包含有关应用程序所有端点的详细信息。您可以浏览端点、查看请求和响应详细信息，并使用API文档快速上手应用程序。

注意：

在使用Swagger 3生成API文档时，需要记住以下几点：

确保在pom.xml文件中添加了Swagger 3依赖项。
在应用程序中创建一个SwaggerConfig类。
在控制文件中添加适当的OpenAPI注解。
在浏览器中输入正确的网址以访问API文档。

常见问题解答

为什么我无法在浏览器中看到API文档？
- 确保您已正确配置SwaggerConfig类并启动了应用程序。
如何自定义API文档的外观？
- 您可以在SwaggerConfig类中使用swagger-ui-html配置自定义API文档的外观。
如何生成不同版本的API文档？
- 您可以在Docket构造函数中设置不同的DocumentationType来生成不同版本的API文档，例如SWAGGER_2或OAS_30。
如何在Swagger 3中管理安全信息？
- 您可以在Docket构造函数中使用securitySchemes方法配置安全信息。
如何将Swagger 3与其他Spring Boot工具集成？
- Swagger 3可以与其他Spring Boot工具集成，例如Spring Security和Spring Data REST。