使用OpenAPI Generator生成Spring Boot服务：多响应类型适配问题

1. 操作是否有误？ #

是的，核心问题在于错误拆分接口且未正确利用OpenAPI的多响应媒体类型声明：

• 你把本应支持内容协商的同一个接口拆成了/user和/getuser两个独立接口，违背了REST规范中通过Accept头实现内容协商的设计逻辑
• OpenAPI定义里没有为同一个接口同时声明application/json和text/plain两种响应类型，导致生成的接口返回类型被固定为单一模型或字符串，无法灵活适配不同的Accept头需求

2. 如何不修改生成的API接口，仅在控制器中实现需求？ #

第一步：修正OpenAPI YAML定义 #

将两个接口合并为一个，同时在responses中声明两种响应媒体类型，示例如下：

openapi: 3.0.3
info:
  title: User Service API
  version: 1.0.0
paths:
  /user:
    get:
      summary: 获取用户信息（支持JSON/文本响应）
      responses:
        '200':
          description: 成功响应，根据Accept头返回对应格式
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPost200Response'
            text/plain:
              schema:
                type: string
components:
  schemas:
    UserPost200Response:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string

重新生成Spring Boot代码后，生成的API接口会返回ResponseEntity<Object>（或适配配置的多类型返回结构），无需手动修改接口。

第二步：在控制器实现中处理内容协商 #

在控制器实现类中，通过获取Accept头判断返回对应格式：

@RestController
public class UserApiController implements UserApi {

    private final ObjectMapper objectMapper;

    public UserApiController(ObjectMapper objectMapper) {
        this.objectMapper = objectMapper;
    }

    @Override
    public ResponseEntity<Object> userGet() {
        // 构建业务模型
        UserPost200Response user = new UserPost200Response();
        user.setId(1);
        user.setUsername("frankmurphy");

        // 获取当前请求的Accept头
        HttpServletRequest request = ((ServletRequestAttributes) RequestContextHolder.getRequestAttributes()).getRequest();
        String acceptHeader = request.getHeader("Accept");

        // 根据头信息返回对应格式
        if (acceptHeader != null && acceptHeader.contains("text/plain")) {
            // 自定义文本格式返回
            String userText = String.format("用户ID: %d, 用户名: %s", user.getId(), user.getUsername());
            return ResponseEntity.ok(userText);
        } else {
            // 默认返回JSON格式模型
            return ResponseEntity.ok(user);
        }
    }
}

进阶优化（处理权重值） #

如果需要支持带权重的Accept头（如Accept: text/plain, application/json;q=0.9），可以用Spring的ContentNegotiationManager更优雅解析：

@Autowired
private ContentNegotiationManager contentNegotiationManager;

@Override
public ResponseEntity<Object> userGet() {
    // 构建业务模型...
    ServletWebRequest webRequest = new ServletWebRequest(request);
    MediaType mediaType = contentNegotiationManager.resolveMediaType(webRequest);
    
    if (MediaType.TEXT_PLAIN.equals(mediaType)) {
        // 返回文本格式
    } else {
        // 返回JSON格式
    }
}

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