Swagger是一个用于构建、文档化和可视化RESTful Web服务的强大工具。它能够自动生成API文档，并提供交互式界面，让开发人员更轻松地浏览、测试和使用API。在本文中，我们将介绍如何在Spring Boot 2.7.*项目中配置Swagger，并展示一些内容丰富的优化。
第一步：添加Swagger依赖
在pom.xml文件中添加Swagger依赖：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
第二步：配置Swagger
在Spring Boot的配置类中添加Swagger的配置：
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("My REST API")
.description("Some custom description of API.")
.version("1.0")
.build();
}
}
上述代码中，首先使用@EnableSwagger2注解开启Swagger支持。然后，通过api()方法创建一个Docket Bean，并配置其基本信息。其中，apis()方法用于指定要包含在API文档中的Controller包路径，paths()方法用于指定要包含的URL路径规则。最后，通过apiInfo()方法配置API文档的描述、版本等信息。
第三步：测试Swagger
启动Spring Boot应用，并访问http://localhost:8080/swagger-ui/，你将看到Swagger的交互式界面。通过该界面，你可以浏览、测试和使用API。
进一步优化
除了基本配置外，你还可以进一步优化Swagger，使其功能更强大，界面更美观。以下是一些常见的优化方案：
1. 添加接口描述
在Controller类或方法上，可以使用Swagger的注解来添加接口描述。例如：
@RestController
@Api(tags = "User API", description = "Operations for managing users")
public class UserController {
@ApiOperation("Get user by ID")
@GetMapping("/users/{id}")
public User getUser(@PathVariable("id") Long id) {
// implementation
}
}
在上述例子中，我们使用@Api注解为整个Controller添加了描述，并使用@ApiOperation注解为某个方法添加了描述。
2. 添加参数描述
在Controller方法的参数上，可以使用Swagger的注解来添加参数描述。例如：
@GetMapping("/users")
public List<User> getUsers(@ApiParam("ID of the user") @RequestParam Long id) {
// implementation
}
在上述例子中，我们使用@ApiParam注解为参数添加了描述。
3. 添加返回类型描述
在Controller方法的返回类型上，可以使用Swagger的注解来添加返回类型描述。例如：
@GetMapping("/users")
public ResponseEntity<List<User>> getUsers() {
// implementation
}
在上述例子中，我们使用ResponseEntity<List<User>>作为返回类型，Swagger会自动处理并添加相应的描述。
4. 配置全局参数
如果你的API中有全局参数，可以通过Swagger的全局配置进行处理。例如：
@Bean
public Docket api() {
// ...other configurations...
return new Docket(DocumentationType.SWAGGER_2)
.globalRequestParameters(Arrays.asList(
new RequestParameterBuilder()
.name("token")
.required(true)
.in(ParameterType.HEADER)
.description("Access token")
.build()
))
// ...other configurations...
}
在上述例子中，我们通过globalRequestParameters()方法添加了一个名为token的全局参数，并指定了其位置、是否必需和描述。
这些只是Swagger的一小部分功能和优化方案，你可以根据实际需求进行更多定制和优化。
结语
在本文中，我们展示了如何在Spring Boot 2.7.*项目中配置Swagger，并介绍了一些内容丰富的优化方案。通过合理配置和优化Swagger，我们可以更好地构建、文档化和可视化RESTful Web服务，提高开发效率和API的易用性。
希望本文对你有所帮助，谢谢阅读！
本文来自极简博客，作者：幽灵船长，转载请注明原文链接：配置Swagger in Spring Boot 2.7.*
