使用MultipartFormDataInput的REST API调用返回404 Not Found问题排查

• 注解继承失效：Swagger 会扫描接口上的 OpenAPI 注解生成文档，所以能正常展示接口，但多数 JAX-RS 实现（如 RESTEasy、Jersey）默认不继承接口方法级的 @Path、@POST、@Consumes 等路由注解，实际运行时框架仅识别实现类上的注解，导致路由未注册，返回 404。
• Content-Type 不匹配：接口指定了 @Consumes(MediaType.MULTIPART_FORM_DATA)，如果 Postman 发送请求时未正确设置请求体类型为 multipart/form-data，框架会认为没有匹配的路由规则，返回 404。
• 路径配置不一致：Postman 请求的路径和实际注册的路由存在差异，比如漏加全局上下文前缀、路径参数格式错误等。

• 方案1：在实现类的重写方法上补充完整的路由注解，确保框架能正确识别路由，修改后的实现类代码如下：

@Authorized
@Path("/")
public class TemplateEndpointImpl extends RestServiceBase
        implements TemplateResource {

    @Override
    @POST
    @Consumes(MediaType.MULTIPART_FORM_DATA)
    @Produces(MediaType.APPLICATION_JSON)
    @Path("/amt/v1/generatedFile/task/{taskId}/secondarysource/{secId}")
    public Response postFile(Long taskId, Long secId, MultipartFormDataInput input) {
        return Response.ok("Test").build();
    }
}

• 方案2：开启 JAX-RS 框架的注解继承开关，不同框架配置不同，比如 RESTEasy 可通过配置参数开启方法级注解继承，无需重复写注解。
• 方案3：校验 Postman 请求配置：
  • 确认请求方法为 POST，路径和 Swagger 展示的完全一致，包含所有全局前缀
  • 确认请求体选择 form-data 类型，且有上传的文件参数
  • 不要手动设置请求头的 Content-Type，让 Postman 自动生成包含 boundary 参数的 multipart 类型头

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