SpringDoc OpenAPI中如何显示DTO类型名称的最佳实践

在SpringDoc OpenAPI 2.8.8版本中，用户界面默认不再显示DTO（数据传输对象）的类型名称，这给开发者识别接口返回数据结构带来了不便。本文将深入分析这一变化的背景原因，并提供完整的解决方案。

问题背景

在2.7.0版本之前，Swagger UI界面会明确显示每个接口返回的DTO类型名称。例如，当接口返回一个UserDTO对象时，UI会清晰地标注"UserDTO"类型。但在2.8.8版本后，UI仅显示通用的"object"类型，虽然JSON定义中仍然包含$ref引用信息。

这种变化对具有多个相似接口但返回不同DTO类型的项目影响较大，开发者需要额外步骤才能确认具体返回类型。

技术原理

SpringDoc OpenAPI底层基于OpenAPI 3.0规范。在生成文档时，它会扫描Spring应用的控制器方法，提取参数和返回类型信息。默认情况下，2.8.8版本简化了UI展示，隐藏了具体的类型名称。

解决方案

要恢复显示DTO类型名称，可以通过以下两种方式实现：

1. 全局配置方案： 在application.properties或application.yml中添加配置：

springdoc.api-docs.resolve-schema-properties=true

2. 自定义处理器方案： 创建自定义的OpenApiCustomizer实现类：

@Bean
public OpenApiCustomizer schemaCustomizer() {
    return openApi -> {
        openApi.getComponents().getSchemas().forEach((name, schema) -> {
            if (schema.get$ref() != null) {
                schema.setType(name);
            }
        });
    };
}

注意事项

• 对于数组类型，需要特殊处理contains属性
• 自定义处理器方案提供了更灵活的展示控制
• 全局配置方案可能影响其他部分的文档生成行为

最佳实践建议

1. 对于简单项目，推荐使用全局配置方案
2. 对于复杂项目，建议采用自定义处理器以获得更好的控制
3. 考虑在团队内部统一文档展示规范
4. 定期检查SpringDoc版本更新对文档展示的影响

通过以上方法，开发者可以恢复DTO类型名称的显示，提高API文档的可读性和开发效率。