rest - ReSpec vs Bikeshed : How to document and publish a standard REST API interface to be implemented by a number of vendors?

Question

我们想要记录一个标准的 REST API 接口(interface)，该接口(interface)将由许多供应商实现。目前我们正在使用 Google Docs 来存储规范。
要求(对大多数人来说必须是通用的):

规范历史 : 我们希望能够引用以前版本的规范。

版本控制 :我们希望将规范存储在版本控制中，以便我们可以根据我们的代码库标记版本并将其与相关的

一起存储

问题 :我们希望允许社区提交问题。

社区/隶属关系 :我们希望与更广泛的社区共享规范，以接收对我们方法的验证。
端点验证器。

格式/工具 :我们希望使用一种易于编辑的格式，并且可以发布为易于理解的形式。

潜在批准 :如果它有用，最好创建一个标准，让它有一条被更广泛采用的途径。

来自 little research有一些相关的标准机构:

IETF (Internet Engineering Task Force):主要使用基于文本的 RFC 格式，但似乎有一些不错的跟踪工具。通常用于较低级别的标准(例如 TCP)，尽管他们也创建了更高级别的标准。

W3C (万维网联盟):如果我们最终通过 W3C 发布，看起来我们需要遵守 pubrules .

WHATWG (Web 超文本应用技术工作组):一个似乎主要关注 HTML5 的工作组。 ，因此与 REST API 规范不太相关。

OASIS (结构化信息标准促进组织):似乎更多的是关于 IETF/W3C 标准之上的业务抽象。

我在网上查看了一些示例，并注意到方法的不同:

YAML : 规范历史，在 GitHub 中版本化，issues on GitHub ，没有明显的隶属关系，使用 DocBook .

JSON-LD : spec history ，版本在 GitHub 中，issues on GitHub , W3C affiliation , 使用 ReSpec (也在 GitHub 上)。

JSON API : spec history ，版本在 GitHub 中，issues on GitHub ，没有明显的隶属关系，似乎使用 Jekyll 和一些自定义模板。

JMAP : 版本在 GitHub, issues on GitHub ，没有明显的隶属关系，似乎使用 Markdown 和一些自定义模板。

HTML 5 (W3C) : 版本在 GitHub, issues on GitHub , W3C affiliation , 使用 Bikeshed .

HTML 5 (WHATWG) : 版本在 GitHub, issues on GitHub , WHATWG affiliation , 使用“专有语言，然后将其后处理为 HTML”(source)。

JSON Schema : 使用 IETF 工具进行版本化，issues on GitHub , IETF affiliation , 使用 IETF RFC format .

CSS 3 : spec history , Mercurial 版本, issues inline in spec , W3C affiliation , 使用 Bikeshed .

对于 REST API，我们应该遵循哪种方法？各自的优点和缺点是什么？

Answer 1

所以关于 Bikeshed 与 ReSpec 的话题，有几点想法:

在选择要依赖的软件时，一个项目相对于另一个项目的技术优势或功能集很少会成为您的决定因素；当然，除非有特定功能是您完成工作绝对需要的，并且并非所有竞争者都提供这些功能。

软件往往来来去去。商业软件也是如此，因为它是开源的。学习曲线越陡峭，迁移成本越高，您在选择工具时就越想考虑工具的 future 。

Bikeshed 的杀手级功能是其跨规范链接数据库集成。但如果你需要它，它只是一个杀手级功能。我怀疑你会给出你当前的用例。

话虽如此，因为它是一些更复杂和以网络为中心的规范编辑的杀手级功能，它就像一 block 磁铁，吸引了社区的关键成员。当这些成员采用 Bikeshed 并将其用于新规范或将现有规范转换为它时，它会增加该工具的吸引力，从而产生滚雪球效应。相反，它使 ReSpec 更难保持其吸引力。拥有一个响应式维护者，其工作是编写规范并且其工具是 Bikeshed 也有帮助。

总而言之，Bikeshed 的 future 比 ReSpec 更光明。因此，即使您不需要 Bikeshed 的额外功能，它的学习曲线有点陡峭并且安装更多，您可能仍然想选择它，因为它具有更大的牵引力，这是以下代码:

它会持续更长的时间，

错误应该得到更快的修复，

它应该改进得更快，

它应该更稳定，

它可能会为您的工作添加一些单板，因为您使用的是酷 child 工具。

但是，您似乎打算指定一个 REST API。我不确定这两种工具是否适合这项工作。您是否考虑过 JSON Schema、JSON Hyper-Schema 和文档工具(如 prmd)的组合？ ?这具有(高度)机器可读性的额外好处，可用于生成用于实现的测试套件、用于不同编程语言的客户端等。

全面披露:我开始使用 ReSpec，为其添加了 Markdown 支持，帮助维护它，最近切换到 Bikeshed 以从其跨规范链接数据库集成中受益。