Springboot 配置 Swagger - 扫清报红障碍，快速接入 API 文档
2024-01-01 05:16:27
Springboot 中 Swagger：快速生成 API 文档的终极指南
在现代 API 开发中，文档是必不可少的。Swagger 是一个强大的工具，可以帮助开发人员轻松生成清晰、可交互的 API 文档。本博客将为您提供在 Springboot 中配置 Swagger 的分步指南，并解决常见错误和提供提示。
添加 Swagger 依赖
首先，在项目的 pom.xml 文件中添加 Swagger 依赖：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
配置 Swagger
接下来，配置 Swagger。在 Springboot 中，可以在 application.yml 或 application.properties 文件中进行配置：
springdoc:
swagger-ui:
path: /swagger-ui.html
添加注解
要生成 API 文档，需要在控制器类中添加 @Api 和 @ApiOperation 注解。@Api 注解用于控制器类，而 @ApiOperation 注解用于控制器类中的方法。
@Api(tags = "用户管理")
public class UserController {
@ApiOperation(value = "创建用户")
@PostMapping
public User createUser(@RequestBody User user) {
return userService.createUser(user);
}
}
启动项目
完成配置后，启动项目。访问 http://localhost:8080/swagger-ui.html 即可查看生成的 API 文档。
常见错误及解决方案
1. “Cannot invoke “org.springframework.web.servlet.mvc.condition.......”” 报错
此报错通常是由不兼容的 Springboot 或 Swagger 版本引起的。确保使用兼容的版本。
2. API 文档中没有显示数据
检查是否在控制器类中正确添加了 @Api 和 @ApiOperation 注解。
3. API 文档显示不正确
检查 Swagger 配置是否正确，并确保使用的是兼容的版本。
提示
- 使用 Swagger 注解时，提供性的文本以增强文档的清晰度。
- 将 Swagger 文档部署到生产环境以方便团队成员和外部用户访问。
- 定期更新 Swagger 文档以反映 API 的更改。
常见问题解答
1. Swagger 是否适用于所有 Springboot 项目？
是的，Swagger 适用于所有 Springboot 项目。
2. Swagger 文档是否可以生成 HTML 和 JSON 格式？
是的，Swagger 可以生成 HTML 和 JSON 格式的文档。
3. 是否可以使用 Swagger 自定義 API 文档的外观和内容？
是的，Swagger 提供了自定義選項來自定義 API 文檔的外觀和內容。
4. Swagger 是否支持 OpenAPI 规范？
是的，Swagger 支持 OpenAPI 规范，使 API 文档可與其他工具和平台互操作。
5. Swagger 是否需要在生产环境中使用？
不，在生产环境中使用 Swagger 不是必需的，但强烈建議這樣做，以便团队成员和外部用户轻松访问 API 文档。
