SpringDoc OpenAPI中Kotlin多行字符串缩进问题的解决方案

在Kotlin开发中，我们经常需要在注解中使用多行字符串来描述API文档。SpringDoc OpenAPI作为一个流行的API文档生成工具，能够自动从代码中的注解生成OpenAPI规范文档。然而，当我们在Kotlin中使用多行字符串时，会遇到一个常见的缩进问题。

问题背景

Kotlin的多行字符串（使用三重引号"""包裹）会保留源代码中的缩进格式。这在注解中使用时会导致生成的OpenAPI文档中出现不必要的缩进空格。例如：

@Schema(description = """
    这是一个用户模型
    包含用户的基本信息
    """)

上述代码生成的文档描述会保留每行前面的缩进空格，这显然不是我们想要的效果。

解决方案演进

最初，开发者可以通过实现GlobalOpenApiCustomizer接口来自定义处理这些缩进问题。这种方法虽然有效，但需要每个项目都重复实现类似的逻辑。考虑到这是一个普遍存在的问题，社区决定将其内置到SpringDoc OpenAPI的核心功能中。

最新的改进将trim-kotlin-indent功能扩展到了@Schema注解，这意味着现在可以自动处理以下场景：

1. @Schema注解中的description属性
2. @Schema注解中的example属性
3. 嵌套的schema属性
4. 数组schema中的项目描述

实现原理

该功能的实现主要基于Kotlin的trimIndent()方法，它会自动移除字符串中所有行共有的最小缩进。在SpringDoc OpenAPI内部，这个处理被集成到了注解处理器中，在生成OpenAPI规范前自动应用。

对于开发者来说，现在可以这样编写代码：

@Schema(
    description = """
        |这是一个用户模型
        |包含用户的基本信息
        """.trimMargin()
)

或者直接依赖SpringDoc的自动处理功能：

@Schema(
    description = """
        这是一个用户模型
        包含用户的基本信息
        """
)

最佳实践

1. 对于简单的单行描述，可以直接使用普通字符串
2. 对于复杂的多行描述，使用三重引号的多行字符串
3. 保持一致的缩进风格，便于阅读和维护
4. 考虑在团队中统一约定是否显式使用trimIndent()方法

总结

SpringDoc OpenAPI对Kotlin多行字符串缩进问题的持续改进，显著提升了开发体验。这一变化使得Kotlin开发者能够更自然地编写API文档注解，而无需担心格式问题。随着这一功能的不断完善，我们可以期待更简洁、更一致的API文档生成体验。

对于已经使用自定义GlobalOpenApiCustomizer的项目，可以考虑评估是否迁移到内置功能，以简化代码维护。同时，这一改进也为未来可能的其他Kotlin特定优化奠定了基础。