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

Question

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

版本控制是这样的:

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

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

• 进行向后兼容的错误修复时的补丁版本

如果我只更新文档(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 本身的表面重述好多少。当客户对结果感到惊讶时，来自客户的后续投诉(错误报告)通常会插入下一轮文档更改。所以，是的，即使开发人员的初衷没有改变，文档确实代表了预期结果方面的重大变化。

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

该文档是功能集的一部分。回填缺失的文档通常是一项功能添加，因此您需要升级次要版本。一个小的修正将是一个补丁。