Openrouteservice自定义模型Swagger规范暴露过多不必要信息的问题解析

在Openrouteservice项目的开发过程中，我们发现了一个关于Swagger API文档生成的问题，该问题导致自定义路由模型(RouteRequestCustomModel)在Swagger规范中暴露了过多不必要的信息，甚至产生了递归依赖，影响了API文档的可读性和可用性。

问题背景

Swagger-core作为API文档生成工具，会遍历所有相关类及其依赖来生成OpenAPI规范。在Openrouteservice的实现中，RouteRequestCustomModel类及其关联类被完整地暴露在Swagger文档中，这导致了两个主要问题：

1. 文档中包含了大量与API实际使用无关的内部类信息
2. 某些类之间存在循环引用，导致Swagger UI在预处理阶段无法正确处理这些递归模式

技术分析

问题的根源在于Swagger-core的默认行为会深度扫描所有类依赖关系。对于RouteRequestCustomModel这样的复杂模型类，它包含了许多内部实现细节和辅助类，这些都不应该直接暴露在API文档中。

在技术实现层面，我们发现GeoJSONFeature类的处理方式值得借鉴。该类通过精心设计的包装器模式，只暴露必要的接口信息，而隐藏了内部实现细节。

解决方案

我们采取了以下技术方案来解决这个问题：

1. 实现专门的包装器类：创建一组专门用于API文档生成的包装器类，这些类只包含必要的字段和结构，屏蔽内部实现细节。

2. 定制模型转换：在API处理流程中，将这些包装器对象转换为内部使用的com.graphhopper.util.JsonFeature对象，确保业务逻辑不受影响。

3. 优化Swagger注解：使用@Schema等Swagger注解精确控制哪些字段和类应该出现在API文档中。

实现细节

在具体实现中，我们重点关注了RouteRequestCustomModel类的改造。通过分析发现，该类的areas属性是导致问题的主要因素之一。我们通过以下方式进行了优化：

1. 创建了专门的AreaWrapper类，仅包含必要的几何信息和属性
2. 实现了从Wrapper到内部JsonFeature的转换逻辑
3. 使用@Schema注解精确控制文档生成行为

这种设计不仅解决了Swagger文档的问题，还提高了代码的可维护性，因为API接口与内部实现得到了更好的分离。

技术价值

这个问题的解决带来了几个重要的技术价值：

1. API文档清晰度提升：终端开发者现在可以看到更加简洁、准确的API文档，只包含他们需要知道的信息。

2. 系统稳定性增强：消除了递归依赖导致Swagger UI崩溃的风险。

3. 架构改进：通过引入包装器模式，实现了更好的关注点分离，为未来扩展奠定了基础。

这个案例也展示了在复杂系统中，API文档生成与实际业务逻辑之间的平衡艺术，以及如何通过适当的设计模式来解决这类问题。