Spring Boot 项目中同时使用 Swagger 和 Javadoc 的完整指南-EW帮帮网

在 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
     */
    @Override
    public 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消费者还是开发维护团队都能从中受益。

Spring Boot 项目中同时使用 Swagger 和 Javadoc 的完整指南

在 Spring Boot 项目中同时使用 Swagger 和 Javadoc 的完整指南

一、Swagger 与 Javadoc 的区别

二、同时使用 Swagger 和 Javadoc 的优势

三、配置指南 - 同时启用两种文档

1. 添加依赖（pom.xml）

2. 代码注释最佳实践

四、生成和使用两种文档

1. Swagger 文档

2. Javadoc 文档

3. 集成两种文档的访问

五、最佳实践与建议

六、常见问题解决方案

七、结论

网站公告

今日签到

热门文章

最新发布