HTTP Restful 语义版本控制

Posted 2023-03-07

【中文标题】HTTP Restful 语义版本控制

【英文标题】：HTTP Restful Semantic Versioning

【发布时间】：2020-03-27 21:52:12

【问题描述】：

目前，我对 API 使用语义版本控制。

版本控制是这样的：

进行不兼容的 API 更改时的主要版本

以向后兼容的方式添加功能时的次要版本

进行向后兼容的错误修复时的 PATCH 版本

如果我只更新文档（swagger、内部文档、YAML 等）以添加示例，或者更正附加到 API 的说明，是否应该增加 PATCH？

感谢您的帮助；）

【参考方案1】：

如果我只更新文档（swagger、内部文档、YAML 等）以添加示例，或者更正附加到 API 的说明，我应该增加 PATCH 吗？

取决于示例/更正。它是否代表了与之前对 API 使用的理解的突破？这是一个非常人为的讨论示例：

API：int plus(int a, int b)

文档：int plus(int a, int b) sums a + b.

上面是作为1.0.0发布的，然后有人查看代码并指出溢出时，函数返回0。

更新的文档：int plus(int a, int b) sums a + b where a < 32767 and b < 32767, otherwise, returns 0.

因此，这是否是一项重大更改，取决于 a + b 溢出时的语言及其行为。有些语言会抛出异常或段错误，而另一些语言通常会简单地返回某种模数结果。假设它是 C，在这种情况下，此文档更改可能是一个重大更改（嗯，实际上可能是大多数编程语言）。

这里的重点是，最初的文档通常并不比 API 本身的表面重述好多少。当客户对结果感到惊讶时，来自客户的后续投诉（错误报告）通常会推动下一轮文档更改。所以是的，即使开发人员的初衷没有改变，但文档确实代表了对预期结果的重大改变。

如果更改了文档以完全符合客户在使用中的期望/见证，那么不，这不是重大更改。

文档是功能集的一部分。回填缺少的文档通常是一个特性添加，所以你会碰到次要版本。一个小的修正将是一个补丁。