HTTP Restful 语义版本控制
HTTP Restful Semantic Versioning
目前，我使用语义版本控制 API。
版本控制是这样的：
进行不兼容的 API 更改时的主要版本
以向后兼容的方式添加功能时的次要版本
修复向后兼容的错误时的 PATCH 版本
如果我只更新文档（swagger、内部文档、YAML 等）来添加示例，或者更正附加到 API 的描述，我应该增加 PATCH 吗？
感谢您的帮助 ;)
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?
取决于 example/correction。它是否代表与以前对 API 的使用的理解有所不同？这是一个非常人为的讨论示例：
API: int plus(int a, int b)
文档：int plus(int a, int b) sums a + b.
上面发布为 1.0.0，然后有人查看代码并指出在溢出时，函数 returns 0.
更新文档：int plus(int a, int b) sums a + b where a < 32767 and b < 32767, otherwise, returns 0.
因此，这是否是重大更改取决于语言及其在 a + b 溢出时的行为。有些语言会抛出异常或段错误，而有些语言通常会简单地 return 某种模数结果。假设它是 C，在这种情况下，此文档更改可能是重大更改（好吧，实际上可能是大多数编程语言）。
这里的要点是初始文档通常并不比 API 本身的肤浅重述好多少。当客户对结果感到惊讶时，来自客户的后续投诉（错误报告）通常会推动下一轮文档更改。所以是的，即使开发人员的初衷没有改变，文档确实代表了预期结果的重大变化。
如果文档已更改以完全匹配客户 expected/witnessed 使用的内容，那么不，这不是重大更改。
文档是功能集的一部分。回填缺失的文档通常是一项功能添加，因此您会提高次要版本。一个小的更正将是一个补丁。
目前，我使用语义版本控制 API。
版本控制是这样的：
进行不兼容的 API 更改时的主要版本
以向后兼容的方式添加功能时的次要版本
修复向后兼容的错误时的 PATCH 版本
如果我只更新文档（swagger、内部文档、YAML 等）来添加示例，或者更正附加到 API 的描述，我应该增加 PATCH 吗？
感谢您的帮助 ;)
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?
取决于 example/correction。它是否代表与以前对 API 的使用的理解有所不同？这是一个非常人为的讨论示例：
API: int plus(int a, int b)
文档：int plus(int a, int b) sums a + b.
上面发布为 1.0.0，然后有人查看代码并指出在溢出时，函数 returns 0.
更新文档：int plus(int a, int b) sums a + b where a < 32767 and b < 32767, otherwise, returns 0.
因此，这是否是重大更改取决于语言及其在 a + b 溢出时的行为。有些语言会抛出异常或段错误，而有些语言通常会简单地 return 某种模数结果。假设它是 C，在这种情况下，此文档更改可能是重大更改（好吧，实际上可能是大多数编程语言）。
这里的要点是初始文档通常并不比 API 本身的肤浅重述好多少。当客户对结果感到惊讶时，来自客户的后续投诉（错误报告）通常会推动下一轮文档更改。所以是的，即使开发人员的初衷没有改变，文档确实代表了预期结果的重大变化。
如果文档已更改以完全匹配客户 expected/witnessed 使用的内容，那么不，这不是重大更改。
文档是功能集的一部分。回填缺失的文档通常是一项功能添加，因此您会提高次要版本。一个小的更正将是一个补丁。