SpringDoc OpenAPI 中请求/响应类名称显示问题的分析与解决

问题背景

在使用SpringDoc OpenAPI库为Spring Boot应用生成API文档时，开发者可能会遇到一个常见问题：在Swagger UI界面中，请求和响应数据模型的名称被简单地显示为"object"，而不是预期的DTO类名。这个问题在SpringDoc OpenAPI的2.8.0及以上版本中表现得尤为明显。

问题表现

当开发者定义了清晰的数据传输对象(DTO)作为控制器方法的参数或返回值时，期望在生成的API文档中看到这些类的名称。例如，如果有一个UserDTO类作为API响应，理想情况下Swagger UI应该显示"UserDTO"作为模型名称。然而，在某些SpringDoc版本中，这些模型仅被标记为"object"，降低了文档的可读性和明确性。

版本差异

这个问题在不同版本的SpringDoc OpenAPI中表现不同：

• 2.7.0及以下版本：正确显示DTO类名
• 2.8.0及以上版本：模型名称被简化为"object"

问题原因

经过分析，这个问题与SpringDoc OpenAPI内部处理模型名称的策略变更有关。在较新版本中，库可能采用了更通用的模型命名方式，导致特定类名信息丢失。

解决方案

要解决这个问题，开发者可以通过以下两种方式之一：

1. 版本回退：暂时回退到2.7.0版本，这是最简单直接的解决方案，但可能无法使用新版本的其他功能。

2. 配置自定义模型名称：在较新版本中，可以通过添加特定配置来显式设置模型名称：

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info().title("API文档"))
            .components(new Components()
                    .addSchemas("UserDTO", new Schema().type("object"))
                    // 添加其他DTO类
            );
}

最佳实践建议

1. 版本选择：评估项目需求，如果模型名称显示对文档很重要，可以考虑暂时停留在2.7.0版本。

2. 文档补充：即使模型名称显示为"object"，也可以通过详细的字段描述和示例值来增强文档的可读性。

3. 持续关注：关注SpringDoc OpenAPI的更新，这个问题可能会在未来的版本中得到修复。

结论

模型名称显示问题虽然不影响API的实际功能，但会影响文档的可用性。开发者应根据项目需求选择合适的解决方案，同时保持对库更新的关注，以便在问题修复后及时升级。