OpenAPI路径扩展处理咨询：Jersey+Spring MVC下带后缀URL的Swagger定义

刚好我之前处理过类似的场景，结合Jersey+Spring MVC的配置，同时满足OpenAPI/Swagger的规范要求，给你梳理几个可行的方案：

要让用户明确知道需要在请求路径里加扩展名，你不能只写/return/{pid}，得把扩展名也纳入路径规则中。最清晰的方式是把扩展名作为一个路径参数，限定只能是xml或json，这样用户在Swagger UI里一眼就懂怎么传请求。

示例的OpenAPI YAML定义如下：

paths:
  /return/{pid}.{format}:
    get:
      summary: 根据ID获取数据，支持XML/JSON格式
      parameters:
        - name: pid
          in: path
          required: true
          schema:
            type: string
          description: 数据ID
        - name: format
          in: path
          required: true
          schema:
            type: string
            enum: [xml, json]
          description: 返回格式，可选xml或json
      responses:
        '200':
          description: 成功返回对应格式的数据
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/YourResponseModel'
            application/json:
              schema:
                $ref: '#/components/schemas/YourResponseModel'

Jersey本身支持带扩展名的路径匹配，有两种实现方式：

方式1：直接在@Path里声明扩展名参数 #

这种方式最直白，控制器方法直接匹配带扩展名的路径，同时通过@Produces声明支持的媒体类型，Jersey会自动根据扩展名生成对应格式的响应：

@GET
@Path("/return/{pid}.{format}")
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getReturnData(@PathParam("pid") String pid, @PathParam("format") String format) {
    // 业务逻辑：根据pid获取数据
    YourResponseModel data = yourDataService.getById(pid);
    // Jersey会自动根据扩展名（.xml/.json）返回对应格式，不用手动处理format参数
    return Response.ok(data).build();
}

方式2：全局配置扩展名识别过滤器 #

如果不想在每个方法的@Path里写扩展名，可以注册Jersey的UriConnegFilter，全局识别路径中的扩展名并映射到对应的媒体类型：

@Configuration
public class JerseyConfig {
    @Bean
    public ResourceConfig resourceConfig() {
        return new ResourceConfig()
                .register(YourReturnController.class)
                // 注册扩展名映射过滤器
                .register(new UriConnegFilter()
                        .addMediaType("xml", MediaType.APPLICATION_XML_TYPE)
                        .addMediaType("json", MediaType.APPLICATION_JSON_TYPE));
    }
}

这时控制器的@Path可以保持简洁的@Path("/return/{pid}")，Jersey会自动处理/return/{pid}.xml和/return/{pid}.json的请求，映射到对应的方法。不过要注意，Swagger文档还是得按之前的方式定义带扩展名的路径，毕竟用户需要明确知道要加后缀。

如果你的项目里用的是Spring MVC控制器（非Jersey），也有两种方案：

方式1：直接匹配带扩展名的路径 #

和Jersey的方式类似，在@GetMapping里直接声明带扩展名的路径，Spring MVC会自动根据扩展名选择响应格式：

@GetMapping(value = "/return/{pid}.{format}", 
            produces = {MediaType.APPLICATION_XML_VALUE, MediaType.APPLICATION_JSON_VALUE})
public ResponseEntity<YourResponseModel> getReturnData(@PathVariable String pid, @PathVariable String format) {
    YourResponseModel data = yourDataService.getById(pid);
    return ResponseEntity.ok(data);
}

前提是你的项目已经引入了对应的消息转换器依赖：比如jackson-dataformat-xml（处理XML）和jackson-databind（处理JSON），这样Spring MVC才能正确序列化数据。

方式2：全局配置内容协商规则 #

通过Spring MVC的配置类全局开启扩展名支持，这样所有控制器都能自动识别路径中的扩展名：

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
        configurer
                // 开启路径扩展名支持
                .favorPathExtension(true)
                // 不忽略Accept头，优先按扩展名处理
                .ignoreAcceptHeader(false)
                // 默认返回JSON格式
                .defaultContentType(MediaType.APPLICATION_JSON)
                // 映射扩展名到媒体类型
                .mediaType("xml", MediaType.APPLICATION_XML)
                .mediaType("json", MediaType.APPLICATION_JSON);
    }
}

这时控制器的@GetMapping可以写成@GetMapping("/return/{pid}")，Spring MVC会自动处理带扩展名的请求。同样，Swagger文档还是要定义带扩展名的路径，确保用户知晓规则。

1. 依赖要配齐：必须引入Jackson XML和JSON的依赖，否则框架无法生成对应格式的响应。
2. Swagger文档要明确：一定要把扩展名的规则写清楚，不能只给/return/{pid}，否则用户不知道要加后缀。
3. 避免路径冲突：如果同时用Jersey和Spring MVC，建议给Jersey的路径加统一前缀（比如/api），和Spring MVC的路径区分开，避免映射冲突。

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