Salvo框架中OpenAPI接口排序问题的解决方案

在基于Rust的Salvo Web框架开发过程中，开发者可能会遇到OpenAPI文档生成时接口排序不符合预期的问题。本文将深入分析这一问题，并提供完整的解决方案。

问题背景

当使用Salvo框架的oapi功能自动生成Swagger/OpenAPI文档时，默认情况下接口会按照路径的字母顺序自动排序。这种排序方式虽然保证了确定性，但可能不符合开发者的业务逻辑展示需求。

问题表现

开发者通常希望：

1. 接口分组能够按照特定顺序排列
2. 同一分组下的接口能够保持注册时的顺序
3. 整体文档结构更符合业务逻辑层次

解决方案

Salvo框架的最新main分支已经提供了解决方案。开发者需要：

1. 单独引入salvo-oapi crate
2. 启用preserve-order特性

这个特性会保持路由注册时的原始顺序，使得生成的OpenAPI文档与代码中的路由定义顺序一致。

实现原理

preserve-order特性的实现基于以下技术点：

1. 路由注册时维护了一个有序集合
2. OpenAPI生成器会优先使用这个有序集合而非重新排序
3. 保持了数据结构在序列化时的插入顺序

最佳实践

在实际项目中，建议：

1. 按照业务模块组织路由注册代码
2. 将相关接口集中注册
3. 使用Router的层级结构来反映API的业务层次

注意事项

1. 该功能需要确保使用最新版本的salvo-oapi
2. 不同版本的排序行为可能有所不同
3. 在大型项目中，保持路由注册顺序的可维护性很重要

通过这种方式，开发者可以完全控制生成的OpenAPI文档的结构和顺序，从而提供更好的API文档体验。