Spring Boot整合Swagger步骤及示例
Spring Boot整合Swagger步骤及示例
步骤1：添加依赖
在`pom.xml`文件中加入Swagger相关的依赖。对于Swagger 2.x版本，通常会使用Springfox，它是Swagger的一个Java实现，可以帮助我们在Spring Boot应用中集成Swagger。在Maven项目中添加如下依赖：
<dependencies>
<!-- Springfox Swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version> <!-- 根据最新稳定版更新此版本号 -->
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version> <!-- 保持与Swagger2版本一致 -->
</dependency>
</dependencies>
```
步骤2：编写Swagger配置类
创建一个Java配置类以初始化Swagger Bean。
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
@Configuration
@EnableSwagger2WebMvc // 如果是Spring Boot 3.x 或者 Spring MVC 可能需要使用 @EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.yourpackage.controller")) // 替换为你的控制器所在包名
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("My Application API")
.description("Documentation for My Application REST APIs")
.contact(new Contact("Your Name", "http://yourwebsite.com", "youremail@example.com"))
.version("1.0")
.build();
}
}
```
步骤3：在Controller中使用Swagger注解
在你的API控制器类或方法上使用Swagger注解来描述接口：
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
@RestController
@RequestMapping("/api/books")
@Api(value = "图书管理", description = "图书相关的API接口")
public class BookController {
@GetMapping("/{id}")
@ApiOperation(value = "获取指定ID的图书信息", notes = "根据图书ID获取图书详细信息")
public ResponseEntity<Book> getBook(@PathVariable Long id) {
// 实现逻辑...
}
// 其他带有Swagger注解的方法...
}
```
步骤4：访问Swagger UI
启动Spring Boot应用后，可以通过以下URL访问Swagger UI界面：
```
http://localhost:8080/swagger-ui/index.html
```
在这里，你可以浏览并测试所有已标记有Swagger注解的API接口。
以上代码展示了如何在Spring Boot项目中整合Swagger用于生成和展示API文档。 1. 首先，在项目的`pom.xml`文件中引入了Springfox的Swagger2依赖，它提供了与Spring Boot集成Swagger的功能，并包含用于展示API文档的Swagger UI。 2. 创建了一个名为`SwaggerConfig`的Java配置类，通过`@Configuration`注解表明这是一个配置类。在这个类中定义了一个`Docket` Bean，用于配置Swagger的行为。`select()`方法指定了哪些接口会被纳入文档生成范围（这里是扫描特定包下的所有Controller类，并包括所有的路径）。`apiInfo()`方法用于设置API的基本信息，如标题、描述、作者等。 3. 在实际的Controller类中，使用了Swagger提供的注解（如`@Api`和`@ApiOperation`）来装饰接口方法。这些注解可以提供更详细的接口描述和参数说明，以便于生成更加清晰易读的API文档。 4. 当Spring Boot应用启动后，通过访问预设的Swagger UI URL（例如`http://localhost:8080/swagger-ui/index.html`），就可以看到由Swagger自动生成并展示的API文档，还可以直接在这个界面上对API进行测试。