宁波建站平台网站突然打不开
一、环境准备与技术选型
1.1 开发环境要求
- JDK 17+
- Maven 3.6+
- IntelliJ IDEA 2023.1+ (或其他支持JDK 17的IDE)
1.2 技术选型说明
- Spring Boot 3.0：基于Jakarta EE 9+规范
- SpringDoc 2.x：支持OpenAPI 3规范的文档工具
- JDK 17：长期支持版本（LTS）
二、实战步骤演示
2.1 初始化项目
通过Spring Initializr创建项目时选择：
- Spring Web
- Lombok（推荐）
- Validation（推荐）
<!-- pom.xml 关键依赖 -->
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.1.0</version>
</dependency>
2.2 基础API示例
@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用户相关操作接口")
public class UserController {@Operation(summary = "获取用户详情", description = "根据ID查询用户详细信息")@GetMapping("/{id}")public User getUser(@Parameter(description = "用户ID") @PathVariable Long id) {return new User(id, "tech_author", "tech@example.com");}@Operation(summary = "创建用户")@PostMappingpublic User createUser(@RequestBody User user) {return user;}
}
2.3 SpringDoc配置类
@Configuration
public class OpenApiConfig {@Beanpublic OpenAPI springShopOpenAPI() {return new OpenAPI().info(new Info().title("电商平台API").description("Spring Boot 3.0实战文档").version("v1.0.0").license(new License().name("Apache 2.0"))).externalDocs(new ExternalDocumentation().description("项目Wiki").url("https://github.com/your-repo"));}
}
2.4 常用配置项
# application.properties
springdoc.swagger-ui.path=/api-docs
springdoc.api-docs.path=/v3/api-docs
springdoc.show-actuator=true
springdoc.cache.disabled=true
三、高级配置技巧
3.1 接口分组配置
@Bean
public GroupedOpenApi publicApi() {return GroupedOpenApi.builder().group("public-apis").pathsToMatch("/api/**").build();
}@Bean
public GroupedOpenApi adminApi() {return GroupedOpenApi.builder().group("admin-apis").pathsToMatch("/admin/**").build();
}
3.2 安全集成配置
@SecurityScheme(name = "BearerAuth",type = SecuritySchemeType.HTTP,bearerFormat = "JWT",scheme = "bearer"
)
四、文档访问与调试
- Swagger UI访问地址：http://localhost:8080/api-docs
- OpenAPI JSON地址：http://localhost:8080/v3/api-docs
五、常见问题排查
5.1 版本兼容性问题
- 确保SpringDoc版本与Spring Boot 3.0兼容
- 使用正确的Jakarta包路径（javax包已废弃）
5.2 文档未生成检查项
- 检查Controller是否被正确扫描
- 验证路径匹配规则
- 查看启动日志是否有异常
六、最佳实践建议
- 使用DTO作为接口参数和返回值
- 为每个响应状态添加@ApiResponse
- 结合Validation注解生成参数约束说明
- 定期清理废弃接口文档
项目完整配置示例：
GitHub示例仓库
注： 本文基于Spring Boot 3.0.6和SpringDoc 2.1.0编写，实际开发时请验证最新版本兼容性。建议结合CI/CD实现文档自动化部署，提升团队协作效率。