时间戳

首页 > 解决方案 > HTTP Restful 语义版本控制

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

问题描述

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

版本控制是这样的：

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

谢谢你的帮助 ;）

标签： semantic-versioning

解决方案

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

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

如果更改了文档以完全匹配客户在使用中所期望/见证的内容，那么不，这不是一个重大变化。

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

推荐阅读