SpringDoc OpenAPI 2.7.0版本中OperationId自定义失效问题解析

问题背景

在SpringDoc OpenAPI 2.7.0版本中，开发者反馈了一个关于OperationId自定义功能失效的问题。具体表现为：当开发者通过OperationCustomizer将operationId设置为null时，生成的OpenAPI规范中仍然会出现"null_1"、"null_2"等自动生成的operationId值，而不是预期的完全移除operationId字段。

技术细节

预期行为

根据OpenAPI规范，operationId字段是一个可选字段（非必填项）。在SpringDoc OpenAPI 2.6.0及更早版本中，当开发者通过自定义器将operationId设置为null时，生成的OpenAPI规范中会完全省略该字段，这是符合预期的行为。

问题表现

升级到2.7.0版本后，同样的自定义代码：

@Bean
public OperationCustomizer operationIdCustomizer() {
    return (operation, handlerMethod) -> {
        operation.setOperationId(null);
        return operation;
    };
}

会导致生成的OpenAPI规范中出现"null_x"形式的operationId，这显然不符合开发者的预期。

问题根源

这个问题源于2.7.0版本中对operationId处理逻辑的变更。新版本中，即使显式设置为null，系统仍然会尝试生成一个默认的operationId，而不是尊重开发者的null设置。

解决方案

项目维护者已经在新版本中修复了这个问题。在2.7.1-SNAPSHOT版本中，当operationId被显式设置为null时，系统会正确地从生成的OpenAPI规范中完全移除该字段，恢复了2.6.0版本的行为。

最佳实践建议

1. 版本选择：如果项目中需要完全控制operationId的生成（包括完全移除该字段），建议使用2.7.1或更高版本。

2. 自定义策略：当需要移除operationId时，可以使用示例中的自定义器代码，但要注意版本兼容性。

3. 规范理解：虽然OpenAPI规范不强制要求operationId，但在某些客户端代码生成工具中，这个字段可能很有用。移除前应考虑下游影响。

总结

这个问题展示了框架升级时可能遇到的微妙行为变化。开发者在使用自定义功能时，应该注意框架版本间的行为差异，并在升级后进行充分的测试验证。SpringDoc OpenAPI团队对这类问题的快速响应也体现了开源项目的优势，开发者可以及时获得问题修复。

对于需要精确控制API文档生成的团队，建议建立完善的版本升级测试流程，特别是对自定义功能的验证，以确保升级不会破坏现有的API契约。