# 搜索依赖
grep -r "swagger" pom.xml
grep -r "springdoc" pom.xml
grep -r "knife4j" pom.xml

@Api(tags = "模块名称", description = "模块功能描述")
@RestController
@RequestMapping("/api/xxx")
public class XxxController {
    // ...
}

@Tag(name = "模块名称", description = "模块功能描述")
@RestController
@RequestMapping("/api/xxx")
public class XxxController {
    // ...
}

@ApiSupport(author = "作者名", order = 1)

@ApiOperation(value = "接口功能名称", notes = "接口用途详细说明")
@ApiResponses({
    @ApiResponse(code = 200, message = "请求成功"),
    @ApiResponse(code = 400, message = "请求参数错误"),
    @ApiResponse(code = 401, message = "未授权，请先登录"),
    @ApiResponse(code = 403, message = "无权限访问"),
    @ApiResponse(code = 404, message = "请求资源不存在"),
    @ApiResponse(code = 500, message = "服务器内部错误")
})
@GetMapping("/xxx")
public Result<List<XxxVO>> getXxx() {
    // ...
}

@Operation(summary = "接口功能名称", description = "接口用途详细说明")
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "请求成功"),
    @ApiResponse(responseCode = "400", description = "请求参数错误"),
    @ApiResponse(responseCode = "401", description = "未授权，请先登录"),
    @ApiResponse(responseCode = "403", description = "无权限访问"),
    @ApiResponse(responseCode = "404", description = "请求资源不存在"),
    @ApiResponse(responseCode = "500", description = "服务器内部错误")
})
@GetMapping("/xxx")
public Result<List<XxxVO>> getXxx() {
    // ...
}

@ApiOperationSupport(
    author = "作者名",
    order = 1,
    ignoreParameters = {"token", "password"}
)

// Swagger 2.x
@ApiImplicitParams({
    @ApiImplicitParam(
        name = "keyword",
        value = "搜索关键词（支持模糊匹配）",
        paramType = "query",
        dataType = "string",
        required = false,
        example = "测试商品"
    ),
    @ApiImplicitParam(
        name = "status",
        value = "状态：0-下架，1-上架",
        paramType = "query",
        dataType = "int",
        required = false,
        example = "1"
    )
})
@GetMapping("/search")
public Result<List<XxxVO>> search(
    @RequestParam(required = false) String keyword,
    @RequestParam(required = false) Integer status
) {
    // ...
}

// Swagger 2.x
@GetMapping("/{id}")
public Result<XxxVO> getById(
    @ApiParam(value = "商品ID", example = "1001", required = true)
    @PathVariable Long id
) {
    // ...
}

// OpenAPI 3.x
@GetMapping("/{id}")
public Result<XxxVO> getById(
    @Parameter(name = "id", description = "商品ID", example = "1001", required = true)
    @PathVariable Long id
) {
    // ...
}

// Swagger 2.x
@PostMapping("/add")
public Result<Long> add(
    @ApiParam(value = "商品信息", required = true)
    @Valid @RequestBody XxxAddReq req
) {
    // ...
}

// OpenAPI 3.x（通常不需要额外注解，VO类注解即可）
@PostMapping("/add")
@RequestBody(description = "商品信息", required = true, content = @Content(schema = @Schema(implementation = XxxAddReq.class)))
public Result<Long> add(@Valid @RequestBody XxxAddReq req) {
    // ...
}

// Swagger 2.x
@ApiImplicitParams({
    @ApiImplicitParam(
        name = "ids",
        value = "商品ID列表",
        paramType = "query",
        dataType = "array",
        allowMultiple = true,
        example = "1001,1002,1003"
    )
})
@GetMapping("/batch")
public Result<List<XxxVO>> batch(@RequestParam List<Long> ids) {
    // ...
}

@Data
@ApiModel(value = "XxxVO", description = "商品视图对象")
public class XxxVO {

    @ApiModelProperty(value = "商品ID", example = "1001", required = true)
    private Long id;

    @ApiModelProperty(value = "商品名称", example = "阿莫西林", required = true)
    private String name;

    @ApiModelProperty(value = "商品价格（元）", example = "25.50", required = true)
    private BigDecimal price;

    @ApiModelProperty(value = "状态：0-下架，1-上架", example = "1")
    private Integer status;

    @ApiModelProperty(value = "创建时间", example = "2025-01-30 10:30:00")
    private LocalDateTime createTime;
}

@Data
@Schema(description = "商品视图对象")
public class XxxVO {

    @Schema(description = "商品ID", example = "1001", requiredMode = Schema.RequiredMode.REQUIRED)
    private Long id;

    @Schema(description = "商品名称", example = "阿莫西林", requiredMode = Schema.RequiredMode.REQUIRED)
    private String name;

    @Schema(description = "商品价格（元）", example = "25.50")
    private BigDecimal price;

    @Schema(description = "状态：0-下架，1-上架", example = "1", allowableValues = {"0", "1"})
    private Integer status;
}

// Swagger 2.x
@ApiModelProperty(hidden = true)
private String internalField;

// OpenAPI 3.x
@Schema(hidden = true)
private String internalField;

@Data
@ApiModel(value = "统一响应结果", description = "所有接口的统一响应格式")
public class Result<T> {

    @ApiModelProperty(value = "响应状态码", example = "200", notes = "200-成功，400-参数错误，500-服务器错误")
    private Integer code;

    @ApiModelProperty(value = "响应消息", example = "操作成功")
    private String message;

    @ApiModelProperty(value = "响应数据", notes = "成功时返回具体业务数据，失败时为null")
    private T data;

    @ApiModelProperty(value = "响应时间戳（毫秒）", example = "1738252800000")
    private Long timestamp;
}

// Swagger 2.x
@ApiResponse(code = 200, message = "请求成功", response = Result.class, responseContainer = "List")

@ApiOperation(
    value = "获取商品列表",
    notes = "响应格式：{code: 200, message: '成功', data: [{id: 1, name: '商品1'}, ...]}"
)

@ApiOperationSupport(
    responses = @IoResponse(code = 200, description = "请求成功", responseClass = "com.xxx.vo.XxxVO")
)

// 类级别
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

// 方法响应
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;

// 参数
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;

// 模型
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

// Knife4j 增强（可选）
import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import com.github.xiaoymin.knife4j.annotations.ApiSupport;

// 类级别
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.Operation;

// 方法响应
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

// 参数
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.parameters.RequestBody;

// 模型
import io.swagger.v3.oas.annotations.media.Schema;

// Knife4j 增强（可选）
import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import com.github.xiaoymin.knife4j.annotations.ApiSupport;

// ✅ 好的示例
@ApiOperation(value = "获取商品详情", notes = "根据商品ID查询商品详细信息")

// ❌ 不好的示例
@ApiOperation(value = "商品", notes = "获取")

// ✅ 好的示例
@ApiImplicitParam(
    name = "status",
    value = "商品状态：0-下架，1-上架，2-已售罄",
    paramType = "query",
    dataType = "int",
    example = "1"
)

// ❌ 不好的示例
@ApiImplicitParam(name = "status", value = "状态", dataType = "int")

@ApiResponses({
    @ApiResponse(code = 200, message = "请求成功"),
    @ApiResponse(code = 400, message = "请求参数错误"),
    @ApiResponse(code = 401, message = "未授权，请先登录"),
    @ApiResponse(code = 403, message = "无权限访问"),
    @ApiResponse(code = 404, message = "请求资源不存在"),
    @ApiResponse(code = 500, message = "服务器内部错误")
})

// ✅ 好的示例
@ApiModelProperty(value = "创建时间", example = "2025-01-30 10:30:00")
private LocalDateTime createTime;

@ApiModelProperty(value = "商品价格", example = "25.50")
private BigDecimal price;

// ❌ 不好的示例
@ApiModelProperty(value = "创建时间", example = "xxx")
private LocalDateTime createTime;

// ✅ 好的示例
@ApiModelProperty(value = "手机号", example = "13800138000")
private String phone;

@ApiModelProperty(value = "身份证号", example = "110101199001011234")
private String idCard;

// ❌ 不好的示例（包含真实敏感信息）
@ApiModelProperty(value = "手机号", example = "13812345678")
private String phone;