SpringDoc OpenAPI中同名内部类导致API文档生成问题的解决方案

在Spring Boot应用开发中，我们经常会使用SpringDoc OpenAPI来自动生成API文档。然而，当项目中存在多个同名内部类时，文档生成会出现一个常见但容易被忽视的问题。

问题现象

当开发者定义了两个不同的DTO类，它们各自包含同名的内部类时，SpringDoc OpenAPI在生成API文档时会出现冲突。例如：

data class Foo1Res(val foo: FooInner) {
    data class FooInner(val bar: String)
}

data class Foo2Res(val foo: FooInner) {
    data class FooInner(val somethingElse: Int)
}

在这种情况下，生成的OpenAPI规范文档中只会保留最后一个FooInner的定义，导致API文档不准确。这会给API使用者带来困惑，因为他们无法从文档中区分这两个内部类的实际结构差异。

问题根源

这个问题源于SpringDoc默认的类名解析机制。默认情况下，SpringDoc会使用简单类名(short class name)作为Schema名称，而不考虑类的完整包路径。当遇到同名类时，后处理的类会覆盖先前的定义。

解决方案

方案一：启用完全限定名(FQN)

最直接的解决方案是配置SpringDoc使用完全限定名(Fully Qualified Name)：

springdoc.use-fqn=true

启用后，类名将包含完整的包路径，如com.example.Foo1Res$FooInner和com.example.Foo2Res$FooInner，从而避免命名冲突。

方案二：自定义类型名称解析器

对于需要更精细控制的场景，可以实现自定义的TypeNameResolver：

class CustomTypeNameResolver(properties: SpringDocConfigProperties) : TypeNameResolver() {
    init {
        useFqn = properties.isUseFqn
    }

    override fun nameForClass(cls: Class<*>?, options: Set<Options?>?): String {
        return super.nameForClass(cls, options).replace("\\$".toRegex(), ".")
    }
}

然后通过自动配置类注册这个解析器：

@AutoConfiguration
class CustomConverter(mapper: ObjectMapper, properties: SpringDocConfigProperties) :
    ModelResolver(mapper, CustomTypeNameResolver(properties))

这种方案不仅解决了命名冲突问题，还能对生成的类名进行额外处理，比如将$替换为更友好的.。

最佳实践建议

1. 命名规范：尽量避免在项目中定义同名内部类，即使它们位于不同的外部类中

2. 文档审查：在重要的API版本发布前，应该仔细检查生成的OpenAPI文档，确保所有数据结构都被正确描述

3. 测试验证：编写集成测试来验证生成的OpenAPI文档是否符合预期

4. 版本控制：当API演进时，考虑使用不同的类名而不是重名类来表示不同版本的数据结构

总结

SpringDoc OpenAPI是一个强大的API文档生成工具，但在处理同名内部类时需要特别注意。通过使用完全限定名或自定义名称解析器，开发者可以确保生成的API文档准确反映实际的代码结构。理解这些解决方案有助于构建更可靠、更易维护的API文档系统。

在实际项目中，建议根据团队的具体需求选择最适合的方案。对于小型项目，启用FQN可能是最简单的解决方案；而对于大型复杂项目，自定义名称解析器可能提供更大的灵活性。