semantic-versioning - HTTP Restful 语义版本控制

Question

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

版本控制是这样的:

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

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

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

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

谢谢你的帮助 ;)

Answer 1

Should I increment the PATCH, if I only update the documentation (swagger, internal documenation, YAML, ...) to add example, or correct a description attach to the API?

取决于示例/更正。它是否代表了之前对 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 本身的表面重述好多少。当客户对结果感到惊讶时，来自客户的后续投诉(错误报告)通常会插入下一轮文档更改。所以是的，即使开发人员的原始意图没有改变，文档确实代表了预期结果方面的重大变化。

如果文档已更改为与客户在使用中期望/见证的完全匹配，那么不，这不是一个重大更改。

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