如何在Swagger中自定义注册接口请求体示例（不含id与roles字段）

Great question! I’ve dealt with this exact Swagger request body issue countless times, so let’s walk through your options clearly—including alternatives to creating a separate UserRegister class.

Option 1: Use Swagger Annotations to Mark Fields as Read-Only/Hidden #

If you want to stick with your existing User entity, you can use Swagger’s built-in annotations to exclude specific fields from the request body example (while still keeping them in the response).

For OpenAPI 3.0+ (springdoc-openapi, the modern replacement for SpringFox): #

Use the @Schema annotation with accessMode = Schema.AccessMode.READ_ONLY on fields that should only appear in responses (not requests):

public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Schema(accessMode = Schema.AccessMode.READ_ONLY) // Hides from request, shows in response
    private Long id;

    private String firstname;
    private String lastname;
    private String email;
    private String password;

    @ManyToMany
    @Schema(accessMode = Schema.AccessMode.READ_ONLY)
    private List<Role> roles;

    // Getters and setters
}

For Swagger 2 (SpringFox): #

Use @ApiModelProperty(hidden = true)—note this hides the field from both requests and responses, so it’s only ideal if you don’t need these fields in the response either:

public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @ApiModelProperty(hidden = true)
    private Long id;

    // ... other fields

    @ManyToMany
    @ApiModelProperty(hidden = true)
    private List<Role> roles;
}

Option 2: Use Jackson @JsonView for Flexible Field Filtering #

If you have multiple API endpoints needing different subsets of User fields, @JsonView is a clean, flexible solution that avoids cluttering your entity with Swagger-specific annotations.

1. Define view classes to represent different field sets:

public class Views {
    // For registration requests (only required fields)
    public static class Register {}
    // For full user responses (all fields)
    public static class Full {}
}

2. Annotate your User entity fields with the appropriate views:

public class User {
    @JsonView(Views.Full.class)
    private Long id;

    @JsonView({Views.Register.class, Views.Full.class})
    private String firstname;

    @JsonView({Views.Register.class, Views.Full.class})
    private String lastname;

    @JsonView({Views.Register.class, Views.Full.class})
    private String email;

    @JsonView({Views.Register.class, Views.Full.class})
    private String password;

    @JsonView(Views.Full.class)
    private List<Role> roles;

    // Getters and setters
}

3. Update your controller method to use the views:

@ApiOperation(value = "Registering seller", response = User.class)
@PostMapping(value = "/seller/register")
@JsonView(Views.Full.class) // Return full user details in response
public User addSeller(
    @RequestBody @Valid @JsonView(Views.Register.class) User user
) {
    return userService.addSeller(user);
}

Swagger (especially springdoc-openapi) will automatically respect @JsonView annotations, showing only Register-marked fields in the request body and all Full-marked fields in the response.

Option 3: Create a DTO Class (UserRegister) #

While this adds an extra class, it’s often the most maintainable solution for long-term projects or team environments. A dedicated DTO explicitly defines exactly what fields are expected for registration, avoiding confusion or side effects from reusing the User entity.

Example UserRegister class:

@ApiModel(value = "UserRegister", description = "Request body for seller registration")
public class UserRegister {
    @NotBlank
    private String firstname;

    @NotBlank
    private String lastname;

    @Email
    @NotBlank
    private String email;

    @NotBlank
    private String password;

    // Getters and setters
}

Update your controller:

@ApiOperation(value = "Registering seller", response = User.class)
@PostMapping(value = "/seller/register")
public User addSeller(@RequestBody @Valid UserRegister userRegister) {
    // Convert DTO to entity (use MapStruct for cleaner mapping in larger projects)
    User user = new User();
    user.setFirstname(userRegister.getFirstname());
    user.setLastname(userRegister.getLastname());
    user.setEmail(userRegister.getEmail());
    user.setPassword(userRegister.getPassword());
    
    return userService.addSeller(user);
}

Which Option Should You Choose? #

• Quick simple fix: Use @Schema(accessMode = READ_ONLY) (OpenAPI 3.0+) if all endpoints using User as a request body don’t need id and roles.
• Flexible multi-scenario solution: Use @JsonView if you have multiple endpoints needing different field subsets of the same entity.
• Long-term maintainability: Use a DTO class like UserRegister—it makes your API contract explicit, prevents accidental exposure of sensitive fields, and avoids polluting your entity with presentation-layer concerns.

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