能否通过Swagger Java注解实现API端点路径级文档及属性按需必填？

你设想的这种通过多个@Path注解标记字段在不同端点下必填性的方式完全不可行——@Path注解的作用是定义API接口的路径，和字段的必填规则没有任何关系，Swagger/OpenAPI也不会识别这种用法。

要实现同一个字段在不同API端点下的必填/非必填差异，有两种常用且靠谱的方案：

方案1：创建不同的DTO类（推荐） #

这是最清晰、最易维护的方式，针对每个端点的需求定义独立的DTO，避免字段规则冲突：

// 公共基类，存放所有端点共享的字段
public class BasePerson {
    private String lastName;
    // 其他共享属性的getter/setter
}

// 用于/endpoint1的DTO：firstName必填
public class Endpoint1Person extends BasePerson {
    @Schema(required = true) // Swagger文档标记必填
    @NotNull // Bean校验标记必填
    private String firstName;
    // getter/setter
}

// 用于/endpoint2的DTO：firstName非必填
public class Endpoint2Person extends BasePerson {
    @Schema(required = false) // Swagger文档标记非必填
    private String firstName;
    // getter/setter
}

然后在Controller中对应端点分别使用这两个DTO：

@RestController
public class PersonController {
    @PostMapping("/endpoint1")
    public ResponseEntity<Void> addPersonForEndpoint1(@RequestBody Endpoint1Person person) {
        // 业务逻辑
        return ResponseEntity.ok().build();
    }

    @PostMapping("/endpoint2")
    public ResponseEntity<Void> addPersonForEndpoint2(@RequestBody Endpoint2Person person) {
        // 业务逻辑
        return ResponseEntity.ok().build();
    }
}

方案2：在接口层面定制OpenAPI Schema（适合不想创建多DTO的场景） #

如果不想新增多个DTO，可以在Controller的方法上直接指定该端点对应的Schema规则，覆盖字段的全局配置：

public class Person {
    // 不设置全局必填规则，交给各个接口单独定义
    private String firstName;
    private String lastName;
    // getter/setter
}

@RestController
public class PersonController {
    @PostMapping("/endpoint1")
    @Operation(
        summary = "通过endpoint1创建Person",
        requestBody = @RequestBody(
            content = @Content(
                schema = @Schema(
                    implementation = Person.class,
                    requiredProperties = {"firstName"} // 指定该端点下firstName必填
                )
            )
        )
    )
    public ResponseEntity<Void> createPerson1(@RequestBody Person person) {
        // 业务逻辑
        return ResponseEntity.ok().build();
    }

    @PostMapping("/endpoint2")
    @Operation(
        summary = "通过endpoint2创建Person",
        requestBody = @RequestBody(
            content = @Content(
                schema = @Schema(implementation = Person.class)
                // 不指定requiredProperties，默认firstName非必填
            )
        )
    )
    public ResponseEntity<Void> createPerson2(@RequestBody Person person) {
        // 业务逻辑
        return ResponseEntity.ok().build();
    }
}

注意：这种方式仅能修改Swagger文档的显示规则，如果需要实际的参数校验（比如拒绝空值），还要在方法内单独处理，或者结合Spring的@Validated和分组校验来实现。

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