在现代的
Java Web开发中，
Swagger 是一个广泛使用的 API 文档生成工具，它可以帮助开发者自动生成 RESTful 接口文档，并提供可视化的 UI 界面进行接口测试。随着
Swagger 的升级，
Swagger 3（也称为 OpenAPI 3）成为主流，以下是
引入和配置
Swagger 3 的完整指南。
### 1. Maven 依赖配置
首先，在 `pom.xml` 文件中
引入 Swagger 3 相关依赖。可以使用 SpringDoc，它是 Spring Boot 项目中支持 OpenAPI 3 的主流实现方式：
```xml
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.6.0</version>
</dependency>
```
该依赖会自动
引入 SpringDoc 的 OpenAPI 3 实现，并提供一个可视化的 UI 界面来查看和测试 API 接口。
### 2. 配置文件设置
在 `application.yml` 或 `application.properties` 文件中配置
Swagger 的访问路径和启用状态：
```yaml
springdoc:
api-docs:
path: /v3/api-docs
swagger-ui:
path: /
swagger-ui.html
enabled: true
operations-sorter: method
show-actuator: true
```
上述配置中：
- `api-docs.path` 指定了 OpenAPI 文档的路径。
- `
swagger-ui.path` 指定了
Swagger UI 的访问路径。
- `enabled` 控制是否启用
Swagger UI。
- `operations-sorter` 指定接口按照方法名排序。
- `show-actuator` 控制是否显示 Spring Boot Actuator 的端点信息。
### 3. 创建
Swagger 配置类
在 Spring Boot 项目中创建一个配置类，用于定义 OpenAPI 文档的基本信息：
```
java
import io.
swagger.v3.oas.models.info.Contact;
import io.
swagger.v3.oas.models.info.Info;
import io.
swagger.v3.oas.models.info.License;
import org.springdoc.core.models.GroupedOpenApi;
import org.springdoc.core.openapi.configuration.SpringDocConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class
SwaggerConfig {
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("public")
.pathsToMatch("/api/**")
.build();
}
@Bean
public SpringDocConfiguration springDocConfiguration() {
return new SpringDocConfiguration();
}
@Bean
public io.
swagger.v3.oas.models.OpenAPI springShopOpenAPI() {
return new io.
swagger.v3.oas.models.OpenAPI()
.info(new Info().title("
Swagger 3 API")
.contact(new Contact().name("Mr. Yu"))
.description("
Swagger 3 测试文档")
.version("v1")
.license(new License().name("Apache 2.0")
.url("https://www.apache.org/licenses/LICENSE-2.0")));
}
}
```
此配置类通过 `@Bean` 注解定义了 OpenAPI 的基本信息，包括标题、描述、版本、联系人和许可证等。
### 4. 在 Controller 中使用注解
为了使
Swagger 更好地识别接口信息，可以在 Controller 类和方法上添加相应的注解：
```
java
import io.
swagger.v3.oas.annotations.Operation;
import io.
swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/api")
@Tag(name = "HomeController", description = "首页接口")
public class HomeController {
@Operation(summary = "获取信息", description = "测试获取信息")
@GetMapping("/test")
public String getInfo() {
return "test";
}
}
```
- `@Tag` 注解用于为 Controller 类添加描述信息。
- `@Operation` 注解用于为具体方法添加接口描述。
### 5. 启动项目并访问
Swagger UI
启动 Spring Boot 项目后，可以通过访问以下 URL 查看
Swagger UI：
```
http://localhost:8080/
swagger-ui.html
```
如果配置中设置了不同的路径，则需要根据实际路径访问。在该页面中，可以看到所有定义的 API 接口，并可以进行测试操作。
### 6. 注意事项
- 在生产环境中，建议将 `springdoc.
swagger-ui.enabled` 设置为 `false`，以避免暴露 API 文档。
- 如果项目中使用了 Spring Security，需要配置权限，确保 `/v3/api-docs` 和 `/
swagger-ui.html` 路径可被访问。
-
Swagger 3 支持多种格式的输出，包括 JSON 和 YAML，开发者可以根据需求选择合适的格式。
###
本文档介绍了如何在Spring Boot项目中引入Springfox Swagger2来创建RESTful API的交互式文档。首先，在pom.xml文件中添加依赖，设置springfox-swagger2的版本号。然后，在启动类上添加@EnableSwagger2注解，启动Swagger2的功能。通过这些步骤，你可以轻松地为你的API生成详细的文档。
扫一扫
2981
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
