Swagger生成REST文档时自定义响应类属性未正常展示问题

数据老陈

2026-8-26

问题原因

这个问题是Swagger/OpenAPI文档生成的常见适配问题，核心成因按出现概率从高到低排列如下：

模型类访问权限不符合要求：你当前定义的FamilyMembersResponse没有加public修饰符，属于包级私有访问级别，绝大多数Swagger实现（比如springdoc-openapi、springfox）默认只会扫描public修饰的类作为文档模型，非public类不会触发属性解析流程，哪怕字段上加了@Schema注解也不会被识别。
类定义位置的隐式问题：如果该类是定义在Controller内部的非静态内部类，JVM会为非静态内部类生成持有外部Controller实例的隐式构造参数，Swagger在做模型序列化解析时无法正常实例化类结构，会直接跳过属性解析。
缺少属性访问器方法：Swagger解析模型属性遵循JavaBean规范，默认通过字段对应的getter/setter方法识别属性，如果你只定义了类字段、没有写对应的get/set方法，也没有用Lombok的@Data/@Getter/@Setter注解自动生成访问器，就会出现类被识别、但属性列表为空的情况。

修复步骤

调整模型类访问权限
如果是单独定义的模型类，把类声明改为public：

@Schema(description = "用户家庭成员查询响应体")
public class FamilyMembersResponse {
    @Schema(description = "用户基础信息", name = "user")
    private User user;
    @Schema(description = "家庭成员列表", name = "family_members")
    private List<FamilyMember> familyMembers;

    // 补全所有字段的getter、setter方法，或在类上加@Data注解
    public User getUser() {
        return user;
    }

    public void setUser(User user) {
        this.user = user;
    }

    public List<FamilyMember> getFamilyMembers() {
        return familyMembers;
    }

    public void setFamilyMembers(List<FamilyMember> familyMembers) {
        this.familyMembers = familyMembers;
    }
}

如果需要把响应类定义在Controller内部，必须加static修饰，同时保持public权限：

@RestController
@RequestMapping("/users")
public class UserController {
    @GetMapping("/{user_uuid}/family")
    public ResponseEntity<FamilyMembersResponse> getUserFamily(@PathVariable("user_uuid") String UUID) {
        // 业务逻辑省略
        FamilyMembersResponse response = new FamilyMembersResponse();
        return new ResponseEntity<>(response, HttpStatus.OK);
    }

    // 必须是public static修饰的内部类
    @Schema(description = "用户家庭成员查询响应体")
    public static class FamilyMembersResponse {
        // 字段、getter/setter和上面一致
    }
}

额外校验：确保关联的User、FamilyMember类也满足public修饰、有对应属性访问器的要求，否则嵌套对象的文档也会出现缺失。

修复后重启服务即可在Swagger文档中看到完整的响应类属性说明，不需要额外调整接口路由的配置。

内容的提问来源于stack exchange，提问作者Julien