docs(swagger): 解决泛型返回类型字段信息不显示问题

- 添加 Swagger 泛型返回类型文档配置说明
- 提供 `@ApiResponse` 注解使用示例
- 明确指定返回数据结构的实现类
- 补充验证方法与适用范围说明
- 强调注解一致性及正确引用实现类的重要性
- 优化 API 文档可读性和可用性

docs/Swagger泛型返回类型字段信息不显示问题解决方案.md

@@ -0,0 +1,66 @@
+# Swagger 泛型返回类型字段信息不显示问题解决方案
+
+## 问题描述
+
+在使用 Swagger/OpenAPI 生成 API 文档时，当接口返回的是泛型类型（如项目中的 `R<T>`）时，Swagger 无法自动推断出泛型参数的具体类型信息，导致在文档中无法正确显示实际返回数据的结构。
+
+具体表现为：接口实际返回 `R<CheckUserBindingResponse>`，但在 Swagger UI 中只显示了 `R` 类的基本结构（code、message、data），而没有显示 data 字段中 `CheckUserBindingResponse` 的具体字段（exists 和 bindingType）。
+
+## 问题原因
+
+Swagger 在处理 Java 泛型时存在局限性，无法在运行时获取泛型参数的具体类型信息，特别是在使用 `ResponseEntity<T>` 或自定义泛型包装类（如项目中的 `R<T>`）时。
+
+## 解决方案
+
+使用 `@ApiResponse` 注解配合 `@Content` 和 `@Schema` 注解来显式告诉 Swagger 接口返回的具体数据结构。
+
+### 实施步骤
+
+1. 在需要明确指定返回类型的 Controller 方法上添加 `@ApiResponse` 注解
+2. 在 `@ApiResponse` 中通过 `content` 属性指定具体的媒体类型和 schema 实现类
+
+### 示例代码
+
+```java
+@Operation(summary = "检查用户绑定关系", description = "检查患者与医生或家属是否存在绑定关系")
+@PostMapping(path = "/check", consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
+@ApiResponse(responseCode = "200", description = "OK",
+             content = @Content(mediaType = "application/json",
+                               schema = @Schema(implementation = CheckUserBindingResponse.class)))
+public R<?> check(@RequestBody CheckUserBindingRequest req) {
+    try {
+        CheckUserBindingResponse response = userBindingService.checkUserBinding(req);
+        return R.success(200, "ok", response);
+    } catch (Exception e) {
+        return R.fail(500, e.getMessage());
+    }
+}
+```
+
+## 注意事项
+
+1. 保持项目中其他接口的一致性，如果其他接口返回类型使用的是 `R<?>`，则此接口也应保持一致
+2. `@ApiResponse` 注解中的 `implementation` 属性应指向实际的数据载体类，而非泛型包装类
+3. 此方法适用于所有需要在 Swagger 文档中明确显示返回数据结构的场景
+
+## 验证方法
+
+1. 重新编译项目确保无编译错误：
+   ```bash
+   mvn clean compile
+   ```
+
+2. 启动应用并访问 Swagger UI 页面（通常为 http://localhost:8080/doc.html）
+
+3. 找到对应的接口，查看其响应模型是否正确显示了所有字段信息
+
+## 适用范围
+
+此解决方案适用于：
+- 所有使用泛型包装类（如 `R<T>`、`ResponseEntity<T>` 等）作为返回类型的接口
+- 需要在 Swagger 文档中明确展示实际返回数据结构的场景
+- 前后端分离项目中为前端开发人员提供准确 API 文档的需求
+
+## 总结
+
+通过显式声明泛型返回类型的实际结构，我们可以有效解决 Swagger 无法自动解析泛型参数类型的问题，为 API 使用者提供更准确、更详细的接口文档信息。这种方法在不改变代码逻辑的前提下，仅通过添加注解的方式优化了 API 文档的可读性和可用性。