Spring Boot 项目中同时使用 Swagger 和 Javadoc 的完整指南
在 Spring Boot 项目中同时使用 Swagger 和 Javadoc 的完整指南
在 Spring Boot 项目中，Swagger 和 Javadoc 可以完全共存并互补使用。它们服务于不同的目的，可以协同工作以提供更全面的文档解决方案。
一、Swagger 与 Javadoc 的区别
| 特性 | Swagger | Javadoc |
|---|---|---|
| 主要用途 | REST API 文档（交互式） | Java 代码文档（技术细节） |
| 目标用户 | API 消费者（前端、移动端） | 开发人员（维护者、团队） |
| 交互性 | 支持在线测试 API | 静态文档 |
| 生成方式 | 运行时扫描注解生成 | 编译时生成 |
| 输出格式 | HTML（带 UI）/JSON | HTML（标准格式） |
| 关注点 | API 契约、端点、参数 | 代码结构、实现细节 |
二、同时使用 Swagger 和 Javadoc 的优势
-
内外兼顾：
-
Swagger：面向外部API消费者
-
Javadoc：面向内部开发人员
-
-
互补内容：
java
复制
下载
/*** 用户服务实现类* <p>* 提供用户相关的业务逻辑操作，包括用户创建、查询和更新等功能。* 具体实现依赖于 {@link UserRepository} 数据访问层。* * @see UserController* @since 1.0.0*/ @Service public class UserServiceImpl implements UserService {// 类实现... } -
文档完整性：
-
Swagger 提供 API 端点文档
-
Javadoc 提供业务逻辑和代码设计文档
-
三、配置指南 - 同时启用两种文档
1. 添加依赖（pom.xml）
xml
复制
下载
运行
<!-- Swagger --> <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.5.0</version> </dependency><!-- Javadoc 插件 --> <build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-javadoc-plugin</artifactId><version>3.6.3</version><executions><execution><id>attach-javadocs</id><goals><goal>jar</goal></goals></execution></executions><configuration><doclint>none</doclint> <!-- 禁用严格检查 --><show>public</show> <!-- 只显示 public 元素 --></configuration></plugin></plugins> </build>
2. 代码注释最佳实践
Controller 层示例（结合使用）：
java
复制
下载
/*** 用户管理控制器* <p>* 提供用户相关的RESTful API接口，包括用户的增删改查操作。* 所有接口都需要JWT认证。* * @see UserService* @since 1.0.0*/
@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用户相关的CRUD操作")
public class UserController {private final UserService userService;public UserController(UserService userService) {this.userService = userService;}/*** 创建新用户* <p>* 接收用户JSON数据并创建新用户记录。用户名必须是唯一的。* * @param user 用户数据传输对象* @return 创建成功的用户信息* @throws ConflictException 当用户名已存在时抛出*/@Operation(summary = "创建用户",description = "创建新的系统用户",responses = {@ApiResponse(responseCode = "201", description = "用户创建成功"),@ApiResponse(responseCode = "409", description = "用户名已存在")})@PostMapping@ResponseStatus(HttpStatus.CREATED)public UserDTO createUser(@RequestBody @Valid @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "用户创建请求",required = true,content = @Content(schema = @Schema(implementation = UserDTO.class))UserDTO user) {return userService.createUser(user);}
}
Service 层示例（Javadoc 为主）：
java
复制
下载
/*** 用户服务实现* <p>* 提供用户相关的业务逻辑实现，包括：* <ul>* <li>用户创建与验证</li>* <li>用户信息查询</li>* <li>用户状态管理</li>* </ul>* * @implNote 使用BCrypt加密密码* @see UserRepository*/
@Service
public class UserServiceImpl implements UserService {private final UserRepository userRepository;private final PasswordEncoder passwordEncoder;public UserServiceImpl(UserRepository userRepository, PasswordEncoder passwordEncoder) {this.userRepository = userRepository;this.passwordEncoder = passwordEncoder;}/*** 创建新用户* * @param userDto 用户数据传输对象* @return 保存后的用户实体* @throws ConflictException 当用户名已存在时抛出* * @see #validateUserUniqueness*/@Overridepublic User createUser(UserDTO userDto) {validateUserUniqueness(userDto.getUsername());User user = new User();user.setUsername(userDto.getUsername());user.setPassword(passwordEncoder.encode(userDto.getPassword()));user.setEmail(userDto.getEmail());return userRepository.save(user);}// 其他方法...
}
四、生成和使用两种文档
1. Swagger 文档
-
访问地址：
http://localhost:8080/swagger-ui.html -
特点：运行时可用，自动更新
2. Javadoc 文档
-
生成命令：
bash
复制
下载
mvn javadoc:javadoc
-
输出位置：
target/site/apidocs/index.html -
特点：需要显式生成，适合归档
3. 集成两种文档的访问
在项目中添加一个文档入口控制器：
java
复制
下载
@Controller
public class DocumentationController {@Value("${server.port}")private int port;@GetMapping("/docs")public String documentationHub(Model model) {model.addAttribute("swaggerUrl", "http://localhost:" + port + "/swagger-ui.html");model.addAttribute("javadocUrl", "/apidocs/index.html"); // 假设将Javadoc复制到static目录return "docs/index";}
}
创建 resources/templates/docs/index.html:
html
复制
下载
运行
<!DOCTYPE html>
<html>
<head><title>项目文档中心</title>
</head>
<body><h1>项目文档中心</h1><div><h2>API 文档 (Swagger)</h2><p>交互式API文档，用于测试和验证端点</p><a th:href="${swaggerUrl}" target="_blank">打开 Swagger UI</a></div><div><h2>技术文档 (Javadoc)</h2><p>代码级技术文档，包含实现细节</p><a th:href="${javadocUrl}" target="_blank">打开 Javadoc</a></div>
</body>
</html>
五、最佳实践与建议
-
注释分工原则：
-
Swagger 注解：专注于API契约（端点、参数、响应）
-
Javadoc 注释：解释业务逻辑、算法和实现细节
-
-
避免重复：
java
复制
下载
// 不推荐 - 内容重复 @Operation(summary = "Get user by ID", description = "Retrieves user details by unique identifier") /*** 根据ID获取用户* 通过唯一标识符检索用户详细信息*/ @GetMapping("/{id}")// 推荐 - 互补内容 @Operation(summary = "Get user by ID", description = "Retrieves user details") /*** 根据用户ID获取完整用户信息* <p>* 内部实现会查询数据库并组装用户关联的角色信息* * @see UserService#getUserWithRoles*/ @GetMapping("/{id}") -
版本控制：
-
将生成的Javadoc纳入版本控制
-
或集成到CI/CD流水线中自动发布
-
-
文档审查：
-
将文档审查纳入代码审查流程
-
使用SonarQube等工具检查文档覆盖率
-
-
补充文档类型：
图表
代码
下载
项目文档
API文档 - Swagger
技术文档 - Javadoc
架构设计文档
数据库文档
部署文档
六、常见问题解决方案
-
Swagger 不显示模型描述：
-
确保在模型类上添加
@Schema注解 -
或者在Javadoc中提供详细描述，Swagger会优先使用注解
-
-
Javadoc 生成失败：
xml
复制
下载
运行
<!-- 在pom.xml中添加配置 --> <configuration><doclint>none</doclint> <!-- 禁用严格检查 --><source>17</source> <!-- 指定Java版本 --> </configuration>
-
保持文档同步：
-
使用CI/CD流水线自动生成文档
-
添加预提交钩子检查文档完整性
-
-
生产环境处理：
java
复制
下载
@Profile("!prod") @Configuration public class SwaggerConfig {// 开发/测试环境启用Swagger }properties
复制
下载
# application-prod.properties springdoc.swagger-ui.enabled=false
七、结论
在 Spring Boot 项目中同时使用 Swagger 和 Javadoc 是最佳实践：
-
Swagger 是面向 API 消费者的前端友好文档
-
Javadoc 是面向开发者的技术实现文档
-
结合使用 提供从接口契约到实现细节的完整文档链
通过合理的分工和集成，两种文档工具可以协同工作，显著提升项目的可维护性和团队协作效率。建议：
-
为新项目同时配置两种文档系统
-
在代码审查中加入文档审查
-
定期检查文档的完整性和准确性
-
将文档生成纳入CI/CD流程
最终形成的文档体系将为项目提供全面的技术支持，无论是API消费者还是开发维护团队都能从中受益。