OpenAPI Generator与Spring：生成的Controllers的用途及使用方法

当你把OpenAPI Generator的interfaceOnly配置设为false时，生成的是带有完整路由注解、参数绑定逻辑但方法体为空的Spring Controller类——这些类严格遵循你提供的OpenAPI Schema定义了接口的路径、请求方式、参数结构和响应格式，但没有具体业务实现。

核心用途 #

• 快速搭建API骨架：不用手动编写@GetMapping/@PostMapping、@PathVariable、@RequestBody这些注解，也不用自己定义响应体结构，生成的Controller已经帮你把API契约转换成了可运行的代码结构，你只需要填充业务逻辑。
• 保证API与文档一致：生成的Controller完全匹配OpenAPI文档的定义，避免出现代码路由和文档描述不一致的问题，减少联调时的沟通成本。
• 兼容现有业务架构：直接在生成的Controller里注入项目已有的Service、Repository等组件，快速对接现有业务逻辑，不需要重新定义接口层。

具体使用方式 #

方式1：直接修改生成的Controller（适合临时或小型项目）

1. 找到生成的Controller类（比如UserController.java）
2. 在类中注入需要的业务依赖（用构造注入或@Autowired）
3. 在空的方法实现里添加业务逻辑，比如查询数据库、调用外部服务，最后返回符合OpenAPI定义的响应对象：

// 生成的Controller类，直接补全实现
@RestController
@RequestMapping("/api/v1")
public class UserController {
    private final UserService userService;

    // 手动添加构造注入
    public UserController(UserService userService) {
        this.userService = userService;
    }

    // 生成的方法，补全业务逻辑
    @GetMapping("/users/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        User user = userService.getUserById(id);
        if (user == null) {
            return ResponseEntity.notFound().build();
        }
        return ResponseEntity.ok(user);
    }
}

方式2：继承生成的Controller（推荐，避免代码被覆盖）

如果后续需要重新生成代码（比如OpenAPI Schema更新），直接修改生成的类会导致代码丢失，这时可以自己写一个业务Controller继承生成的类，重写需要实现的方法：

// 生成的Controller类（不要修改，后续可重新生成）
public class GeneratedUserController {
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        // 默认空实现，比如返回404
        return ResponseEntity.notFound().build();
    }
}

// 自定义业务Controller，继承生成的类
@RestController
@RequestMapping("/api/v1")
public class UserController extends GeneratedUserController {
    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @Override
    public ResponseEntity<User> getUserById(Long id) {
        User user = userService.getUserById(id);
        return user != null ? ResponseEntity.ok(user) : ResponseEntity.notFound().build();
    }
}

这样后续重新生成代码时，只需要替换GeneratedUserController，自己写的业务代码不会被覆盖，同时依然能保证API契约的一致性。

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