JavaDoc 编写指南

SpringDoc 基于 JavaDoc 注释自动生成 API 文档，因此编写规范的 JavaDoc 注释是使用 SpringDoc 的关键。本章节将详细介绍如何编写高质量的 JavaDoc 注释。

JavaDoc 基础语法

基本结构

JavaDoc 注释以 /** 开始，以 */ 结束，每行以 * 开头：

java

/**
 * 这是类或方法的描述
 * 
 * @param 参数名 参数描述
 * @return 返回值描述
 * @throws 异常类型 异常描述
 */

常用标签

标签	用途	示例
`@param`	描述方法参数	`@param id 用户ID`
`@return`	描述返回值	`@return 用户对象`
`@throws`	描述可能抛出的异常	`@throws NotFoundException 当用户不存在时`
`@deprecated`	标记为已弃用	`@deprecated 请使用新的API`
`@see`	引用其他类或方法	`@see UserService#getUser`
`@since`	指定引入版本	`@since 1.0.0`
`@version`	版本信息	`@version 1.0.0`
`@author`	作者信息	`@author lcz`

控制器类 JavaDoc 示例

基础控制器

java

/**
 * 用户管理控制器
 * <p>
 * 提供用户的增删改查等功能，包括用户信息管理、权限控制等。
 * 所有接口都需要用户认证。
 * </p>
 * 
 * @author lcz
 * @version 1.0.0
 * @since 1.0.0
 * @see UserService
 * @see User
 */
@RestController
@RequestMapping("/api/users")
public class UserController {

    private final UserService userService;

    /**
     * 构造函数注入UserService
     * 
     * @param userService 用户服务实例
     */
    public UserController(UserService userService) {
        this.userService = userService;
    }
}

查询接口

java

/**
 * 分页查询用户列表
 * <p>
 * 支持按用户名、邮箱、状态等条件筛选用户数据。
 * 结果按创建时间降序排列，支持分页查询。
 * </p>
 * 
 * @param username 用户名，支持模糊查询
 * @param email 邮箱地址，支持模糊查询
 * @param status 用户状态，可选值：ACTIVE, INACTIVE, LOCKED
 * @param page 页码，从0开始
 * @param size 每页大小，默认10，最大100
 * @return 用户分页数据，包含用户列表和分页信息
 * @throws IllegalArgumentException 当分页参数无效时
 * @see UserStatus
 * @see Page
 */
@GetMapping
public Page<User> getUsers(
        @RequestParam(required = false) String username,
        @RequestParam(required = false) String email,
        @RequestParam(required = false) UserStatus status,
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "10") int size) {
    
    return userService.findUsers(username, email, status, page, size);
}

详情查询接口

java

/**
 * 根据ID获取用户详情
 * <p>
 * 获取指定用户的完整信息，包括基本信息、角色、权限等。
 * 如果用户不存在，将返回404错误。
 * </p>
 * 
 * @param id 用户ID，必须为正整数
 * @return 用户详情信息
 * @throws UserNotFoundException 当用户不存在时
 * @see UserDetail
 */
@GetMapping("/{id}")
public UserDetail getUserDetail(@PathVariable Long id) {
    return userService.getUserDetail(id);
}

创建接口

java

/**
 * 创建新用户
 * <p>
 * 创建一个新的用户账户，系统会自动生成用户ID。
 * 用户名和邮箱必须唯一，密码会自动加密存储。
 * </p>
 * 
 * @param userRequest 用户创建请求，包含用户名、邮箱、密码等信息
 * @return 创建成功的用户信息，包含生成的用户ID
 * @throws InvalidUserException 当用户数据无效时
 * @throws DuplicateUsernameException 当用户名已存在时
 * @throws DuplicateEmailException 当邮箱已存在时
 * @see UserRequest
 * @see User
 */
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
public User createUser(@RequestBody @Valid UserRequest userRequest) {
    return userService.createUser(userRequest);
}

更新接口

java

/**
 * 更新用户信息
 * <p>
 * 更新指定用户的信息，支持部分字段更新。
 * 只有用户本人或管理员可以更新用户信息。
 * </p>
 * 
 * @param id 用户ID
 * @param userUpdateRequest 用户更新请求，包含需要更新的字段
 * @return 更新后的用户信息
 * @throws UserNotFoundException 当用户不存在时
 * @throws AccessDeniedException 当没有权限更新时
 * @see UserUpdateRequest
 * @since 1.1.0
 */
@PutMapping("/{id}")
public User updateUser(
        @PathVariable Long id,
        @RequestBody @Valid UserUpdateRequest userUpdateRequest) {
    
    return userService.updateUser(id, userUpdateRequest);
}

删除接口

java

/**
 * 删除用户
 * <p>
 * 软删除指定用户，用户数据不会从数据库中物理删除。
 * 只有管理员可以删除用户。
 * </p>
 * 
 * @param id 用户ID
 * @throws UserNotFoundException 当用户不存在时
 * @throws AccessDeniedException 当没有权限删除时
 * @deprecated 使用 {@link #deactivateUser} 方法替代，设置状态为INACTIVE
 */
@DeleteMapping("/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void deleteUser(@PathVariable Long id) {
    userService.deleteUser(id);
}

数据模型类 JavaDoc 示例

请求对象

java

/**
 * 用户创建请求
 * <p>
 * 用于接收用户创建请求的数据传输对象。
 * 所有字段都经过验证，确保数据的有效性。
 * </p>
 * 
 * @author lcz
 * @version 1.0.0
 * @since 1.0.0
 */
public class UserRequest {
    
    /**
     * 用户名
     * <p>
     * 用户名必须唯一，长度在3-20个字符之间，
     * 只能包含字母、数字和下划线。
     * </p>
     */
    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度必须在3-20个字符之间")
    @Pattern(regexp = "^[a-zA-Z0-9_]+$", message = "用户名只能包含字母、数字和下划线")
    private String username;
    
    /**
     * 邮箱地址
     * <p>
     * 邮箱地址必须唯一，且符合邮箱格式规范。
     * </p>
     */
    @NotBlank(message = "邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    private String email;
    
    /**
     * 密码
     * <p>
     * 密码长度至少8位，必须包含字母和数字。
     * 系统会自动对密码进行加密存储。
     * </p>
     */
    @NotBlank(message = "密码不能为空")
    @Size(min = 8, message = "密码长度至少8位")
    @Pattern(regexp = "^(?=.*[A-Za-z])(?=.*\\d)[A-Za-z\\d@$!%*#?&]{8,}$", 
             message = "密码必须包含字母和数字")
    private String password;
    
    // getter 和 setter 方法...
}

响应对象

java

/**
 * 用户详情响应
 * <p>
 * 用于返回用户详细信息的响应对象。
 * 包含用户的基本信息、角色、权限等完整数据。
 * </p>
 * 
 * @author lcz
 * @version 1.0.0
 * @since 1.0.0
 */
public class UserDetail {
    
    /**
     * 用户ID
     */
    private Long id;
    
    /**
     * 用户名
     */
    private String username;
    
    /**
     * 邮箱地址
     */
    private String email;
    
    /**
     * 用户状态
     * <p>
     * 可能的值：ACTIVE(激活), INACTIVE(未激活), LOCKED(锁定)
     * </p>
     */
    private UserStatus status;
    
    /**
     * 创建时间
     * <p>
     * 用户账户的创建时间，格式：yyyy-MM-dd HH:mm:ss
     * </p>
     */
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime createdAt;
    
    /**
     * 最后登录时间
     * <p>
     * 用户最后一次登录的时间，格式：yyyy-MM-dd HH:mm:ss
     * 如果用户从未登录过，此字段为null。
     * </p>
     */
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime lastLoginAt;
    
    /**
     * 用户角色列表
     * <p>
     * 用户拥有的所有角色，用于权限控制。
     * </p>
     */
    private List<Role> roles;
    
    // getter 和 setter 方法...
}

枚举类 JavaDoc 示例

java

/**
 * 用户状态枚举
 * <p>
 * 定义用户账户的各种状态，用于用户管理和权限控制。
 * </p>
 * 
 * @author lcz
 * @version 1.0.0
 * @since 1.0.0
 */
public enum UserStatus {
    
    /**
     * 激活状态
     * <p>
     * 用户账户正常，可以正常使用所有功能。
     * </p>
     */
    ACTIVE("激活"),
    
    /**
     * 未激活状态
     * <p>
     * 用户账户已创建但未激活，需要用户通过邮箱验证激活。
     * </p>
     */
    INACTIVE("未激活"),
    
    /**
     * 锁定状态
     * <p>
     * 用户账户被管理员锁定，无法登录和使用系统功能。
     * 通常由于违规操作或安全原因导致。
     * </p>
     */
    LOCKED("锁定");
    
    /**
     * 状态描述
     */
    private final String description;
    
    /**
     * 构造函数
     * 
     * @param description 状态描述
     */
    UserStatus(String description) {
        this.description = description;
    }
    
    /**
     * 获取状态描述
     * 
     * @return 状态描述
     */
    public String getDescription() {
        return description;
    }
}

最佳实践

1. 注释完整性

为所有公共类、方法、字段添加 JavaDoc 注释
注释应该简洁明了，避免冗余
使用完整的句子，以句号结尾

2. 参数描述

详细描述每个参数的作用、格式和约束
对于复杂参数，提供示例值
说明参数的默认值和可选性

3. 返回值描述

清楚说明返回值的类型和内容
对于集合类型，说明元素的类型
说明可能的空值情况

4. 异常说明

使用 @throws 标签说明可能抛出的异常
说明异常的原因和触发条件
提供异常处理的建议

5. 版本信息

使用 @since 标签标记功能引入的版本
使用 @deprecated 标签标记已弃用的功能
保持版本信息的一致性

6. 引用关系

使用 @see 标签建立类和方法之间的引用关系
提供相关类的链接，帮助理解代码结构

7. 格式化规范

使用 HTML 标签格式化注释内容
使用 <p> 标签分段
使用 <code> 标签标记代码
使用 <pre> 标签保留代码格式

常见错误

1. 注释不完整

java

// ❌ 错误示例
/**
 * 获取用户
 */
public User getUser(Long id) {
    return userService.getUser(id);
}

// ✅ 正确示例
/**
 * 根据ID获取用户信息
 * 
 * @param id 用户ID
 * @return 用户对象，如果用户不存在则返回null
 */
public User getUser(Long id) {
    return userService.getUser(id);
}

2. 参数描述不准确

java

// ❌ 错误示例
/**
 * @param id ID
 */
public User getUser(Long id) {
    return userService.getUser(id);
}

// ✅ 正确示例
/**
 * @param id 用户ID，必须为正整数
 */
public User getUser(Long id) {
    return userService.getUser(id);
}

3. 缺少异常说明

java

// ❌ 错误示例
/**
 * 删除用户
 */
public void deleteUser(Long id) {
    userService.deleteUser(id);
}

// ✅ 正确示例
/**
 * 删除用户
 * 
 * @param id 用户ID
 * @throws UserNotFoundException 当用户不存在时
 * @throws AccessDeniedException 当没有权限删除时
 */
public void deleteUser(Long id) {
    userService.deleteUser(id);
}

通过遵循这些规范和最佳实践，您可以编写出高质量的 JavaDoc 注释，让 SpringDoc 生成更加完善和易读的 API 文档。

JavaDoc 编写指南 ​

JavaDoc 基础语法 ​

基本结构 ​

常用标签 ​

控制器类 JavaDoc 示例 ​

基础控制器 ​

查询接口 ​

详情查询接口 ​

创建接口 ​

更新接口 ​

删除接口 ​

数据模型类 JavaDoc 示例 ​

请求对象 ​

响应对象 ​

枚举类 JavaDoc 示例 ​

最佳实践 ​

1. 注释完整性 ​

2. 参数描述 ​

3. 返回值描述 ​

4. 异常说明 ​

5. 版本信息 ​

6. 引用关系 ​

7. 格式化规范 ​

常见错误 ​

1. 注释不完整 ​

2. 参数描述不准确 ​

3. 缺少异常说明 ​

JavaDoc 编写指南

JavaDoc 基础语法

基本结构

常用标签

控制器类 JavaDoc 示例

基础控制器

查询接口

详情查询接口

创建接口

更新接口

删除接口

数据模型类 JavaDoc 示例

请求对象

响应对象

枚举类 JavaDoc 示例

最佳实践

1. 注释完整性

2. 参数描述

3. 返回值描述

4. 异常说明

5. 版本信息

6. 引用关系

7. 格式化规范

常见错误

1. 注释不完整

2. 参数描述不准确

3. 缺少异常说明