OpenAPI Generator Spring：控制器自定义参数与模型注解问题

一、核心问题解决办法 #

1. 控制器添加非OpenAPI定义参数 #

别直接重写生成的抽象控制器方法，换两种实用方式：

• 自定义控制器继承生成的抽象类，用@GetMapping/@PostMapping复用原接口路径，自由添加UriComponentsBuilder、Principal这类框架支持的参数，Spring MVC会自动解析。
• 生成代码时添加参数--additional-properties interfaceOnly=true，让工具只生成API接口类，自定义控制器实现该接口，直接在实现方法里加所需参数，只要请求路径、HTTP方法和接口一致，Spring就能正确映射。

示例代码：

@RestController
public class UserController implements UserApi {
    @Override
    public ResponseEntity<User> getUserById(String id, Principal principal, UriComponentsBuilder uriBuilder) {
        // 业务逻辑实现
        return ResponseEntity.ok(new User());
    }
}

2. 给生成模型加JPA注解 #

绝对不要直接修改生成的模型类（重新生成会覆盖），推荐两种生产级方案：

• DTO与实体类分离：生成的模型作为API层的DTO，单独编写JPA实体类，用MapStruct这类工具做自动映射。这是最佳实践，能实现API层和持久化层解耦，避免API变更影响数据库结构。
• 自定义OpenAPI扩展+模板改造：在OpenAPI的schema里加x-jpa-*自定义字段，比如：

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        posts:
          type: array
          items:
            $ref: '#/components/schemas/Post'
          x-jpa-annotation: '@OneToMany(mappedBy = "user")'

然后修改OpenAPI Generator的Freemarker模板，读取这些扩展字段，自动在生成的模型字段上插入JPA注解。

3. 自动生成Spring Security权限注解 #

通过OpenAPI扩展字段+模板定制实现：
在OpenAPI的接口定义里给每个operation加x-security-preauthorize扩展，比如：

paths:
  /users/{id}:
    get:
      security:
        - OAuth2: [user:read]
      x-security-preauthorize: '@authService.hasPermission(principal, "USER_READ")'
      responses:
        '200':
          description: 成功获取用户信息

修改生成控制器的模板，读取这个扩展值，自动在方法上添加@PreAuthorize注解，无需手动编写。

二、OpenAPI Generator定位匹配度 #

你的需求是最大化自动生成代码+结合Spring生态特性，工具完全能满足，但它的核心定位是基于OpenAPI规范生成跨语言通用API代码，默认模板不会绑定Spring的所有专属特性。要适配Spring Boot/Security/JPA，需要做模板定制或扩展，这是生产环境中很常规的操作，并非工具定位和需求不符。

如果想零定制快速上手，也可以试试Spring官方的SpringDoc OpenAPI配合Spring Data REST，但后者更适合简单CRUD场景，复杂业务还是需要自定义控制器。

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