OpenAPI规范项目中Schema文件的清理与重构

在OpenAPI规范项目的开发过程中，项目团队近期对Schema文件的管理方式进行了重要调整。这一变更主要涉及项目仓库中Schema文件的存放位置和发布流程的优化，旨在为开发者提供更清晰、更规范的Schema使用体验。

背景与问题

OpenAPI规范项目长期在main分支的/schemas目录下存放着各种版本的Schema文件。这些文件包括1.2、2.0、3.0和3.1等不同版本的OpenAPI Schema定义。然而，这种存放方式存在几个问题：

1. 开发分支和主分支的Schema文件混在一起，导致用户可能误用开发中的Schema
2. 官方发布的Schema与开发中的Schema没有明确区分
3. 历史版本的Schema管理不够规范

解决方案

项目团队经过讨论，决定实施以下改进措施：

1. 分离开发与发布流程：将开发中的Schema文件移至dev分支，确保main分支只包含稳定发布的Schema
2. 建立归档机制：创建/_archive_目录，用于存放不再维护的历史版本Schema
3. 优化发布渠道：通过spec.openapis.org网站作为Schema的官方发布渠道

具体实施步骤

1. 识别并移除构建依赖：首先确保构建过程不再依赖/schemas目录下的工件
2. 启用dev分支的Schema构建：在vX.Y-dev分支上启用Schema的构建和发布流程
3. 调整工作流：禁用main分支上的Schema发布工作流，改为从dev分支同步
4. 历史版本处理：
   • 将v1.2和v2.0 Schema移至/_archive_目录
   • 保留v3.0 Schema及其测试用例，同样归档处理
   • 删除main分支上的3.1 Schema测试文件

技术考量

值得注意的是，v2.0 Schema的所有权问题需要特别处理。由于v2.0 Schema的$id指向swagger.io域，且相关npm包也不属于OAI组织，项目团队决定将其归档而非直接删除。

对于开发者而言，建议采用以下最佳实践：

• 在构建时从spec.openapis.org获取Schema
• 在安装时验证Schema的校验和
• 运行时使用本地缓存的Schema副本

总结

这次Schema管理方式的调整，体现了OpenAPI项目团队对规范性和用户体验的重视。通过清晰的版本隔离和发布渠道优化，开发者现在可以更明确地获取和使用不同状态的Schema定义。这一变更也为未来的版本演进提供了更灵活的管理框架。