功能简介

如今，开放 API 已成为技术团队向外部提供服务和数据的重要手段。然而，随着业务的不断发展以及底层技术的持续升级，团队提供的 API 也必然会经历多个版本的迭代。这种变化是不可避免的，因为团队需要根据市场需求和技术的进步，优化现有功能、增加新特性并修复漏洞。

在这个过程中，API 的多个版本不仅有助于确保不同用户群体的兼容性需求，还能够提供更稳定和创新的服务体验。与此同时，团队必须做好版本管理和兼容性维护，以尽量减少对现有用户的影响，确保业务的连续性和可靠性。

应用场景

团队需要对外部同时提供多个版本的 API，可能包括最新版、稳定版、长期维护版等，用以减少对旧版用户使用影响。

核心能力

• 全量创建

  可以基于现有 API 版本，创建一个包含此版本中全部接口副本的新 API 版本。创建完成后可以任意修改版本中的每个接口内容。当然，也可以选择从空白创建一个新的 API 版本，然后再向这个空白 API 版本里填写接口内容。

• 整体分享

  可以从项目已创建好的 API 版本中选择一个或多个版本进行发布，选择发布的版本内的全部 API 都会被外部读者看到。可以在发布时设置 API 版本对外展示名称以及 slug 设置，用以给读者更好的阅读体验。

• 一键切换

  如果已经设置好了发布多个 API 版本，则访问项目公开地址时，即可以在项目名称右边看到发布版本切换标识。点击即可看到此项目所有被设置发布的 API 版本，点击一个发布版本后，即可切换查看该版本内的所有接口相关内容。

提示

“API 版本”与“迭代分支”的区别

• API 版本：主要用来发布给外部用户使用。当整体接口发生非常大的变更且新旧版本存在较多不兼容的时候，建议创建一个新的 API 版本。 API 版本里包含完整的全量接口，而不仅仅是新增或有改动的接口；
• 迭代分支：主要用来团队内部迭代开发使用。与敏捷开发里的“迭代”相一致，建议每次迭代都创建一个迭代分支，迭代完成后合并到主分支。迭代分支里一般仅包含当前迭代“新增和有改动的接口”，不包含在本次迭代没有改动的接口。