ReSpec与Bikeshed：如何记录和发布由许多供应商实施的标准REST API接口？

Question

我们想要记录一个标准的REST API接口，该接口将由许多供应商实现。目前，我们正在使用Google文档来存储规范。

要求（对大多数人来说必须是共同的）：

• 规范历史记录​​：我们希望能够引用规范的先前版本。
• 版本控制：我们希望将规范存储在版本控制中，以便我们可以根据代码库标记版本并将其与相关的
一起存储
• 问题：我们希望允许社区提交问题。
• 社区/联盟：我们希望与更广泛的社区分享规范，以便接收有关我们方法的验证。 终点验证器。
• 格式/工具：我们希望使用易于编辑的格式，并且可以将其发布为易于理解的格式。
• 潜在的批准：如果它有用，那么创建一个标准，以便更广泛地采用该标准将是一件好事。

从little research开始，有一些相关的标准机构：

• IETF （互联网工程任务组）：主要使用基于文本的RFC格式，但似乎有一些不错的跟踪工具。通常对于较低级别的标准（例如TCP），尽管他们也创建了更高级别的标准。

• W3C （万维网联盟）：如果我们最终通过W3C发布，看起来我们需要遵守{{3} }。

• pubrules （Web超文本应用技术工作组）：一个似乎主要关注WHATWG的组，因此与REST API规范的相关性较低。

• HTML5 （结构化信息标准促进组织）：似乎更多是关于IETF / W3C标准之上的业务抽象。

我已经在网上看了几个例子，并注意到方法的不同之处：

• OASIS ：规范历史记录​​，在GitHub中版本化，YAML，没有明显的从属关系，使用issues on GitHub。

• DocBook ：JSON-LD，在GitHub版本化，spec history，issues on GitHub，使用W3C affiliation（也在ReSpec）。

• GitHub ：JSON API，在GitHub中版本化，spec history，没有明显的从属关系，似乎使用了Jekyll和一些自定义模板。

• issues on GitHub ：在GitHub版本化，JMAP，没有明显的从属关系，似乎使用了markdown和一些自定义模板。

• issues on GitHub ：在GitHub版本化，HTML 5 (W3C)，issues on GitHub，使用W3C affiliation。

• Bikeshed ：在GitHub版本化，HTML 5 (WHATWG)，issues on GitHub，使用＆＃34;专有语言，然后进行后处理HTML＆＃34; （WHATWG affiliation）。

• source ：使用IETF工具进行版本化，JSON Schema，issues on GitHub，使用IETF affiliation。

• IETF RFC format ：CSS 3，在Mercurial版本中，spec history，issues inline in spec，使用W3C affiliation。

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

Answer 1

鉴于它是基于REST的API，W3C最相关。 WHATWG过于关注HTML，IETF会导致规格不太可读，而OASIS可能过于模糊。

所有机构都同意RFC2119，所以值得确保在规范中使用它。

如果选择了W3C，则必须遵循Pubrules（有一个新的W3C pubrules validator，可通过npm和here访问。 Two main formats/tools are currently popular，supported by the W3C's tooling，如here所述：

  

ReSpec和Bikeshed：由于W3C“pubrules”标记可以证明是重复的，有时很难做到正确，因此开发了许多工具来帮助人们制作它 - 这是两个主要的。 ReSpec文档基本上是有效的HTML，有一些额外的配置，JS库变成真实的东西; Bikeshed是一个Python预处理器，可以应用于HTML，但更常用于Markdown模式。

N.B。在ReSpec和Bikeshed之前的Anolis，一个较旧的预处理器，已经declared dead by it's author。

W3C目前正在进行process of modernisation。名为Echidna的新W3C项目（基于GitHub）支持ReSpec和Bikeshed自动发布，但后者只有recently been implemented，目前仅适用于inside the W3C。

使用上述任一工具都可以在specref.org（W3C规范所依赖的参考文献数据库）中对标准进行索引。

关于以下每个选项的说明：

• <强> ReSpec

  • ReSpec正在W3C中使用并积极维护。
  • ReSpec显然是does support Markdown，但the feature is undocumented。
  • Spec Generator似乎位于W3C中的common use for ReSpec CI，可以访问outside the W3C（used to be internal）。
  • 就CI替代方案而言：
    • Echidna是针对ReSpec CI的新官方推荐，但目前仅适用inside the W3C。
    • Publican是一个GitHub钩子侦听器，它生成编写的规范，由ReSpec或Bikeshed解析。很难说项目的状态，因为它似乎已经停止（Robin最初创建了ReSpec，并且做了很多work for webplatform.org，但项目可能已经改变了方向）。使用Bikeshed CI的实际Bikeshed可能更好。它还runs in Docker（见gist）。
  • 有various articles讨论将ReSpec与GitHub和publishing process一起使用。
  • 有人说ReSpec is more accessible。
  • ReSpec规范的示例：here，here，here，here
  • ReSpec CI示例：here（针鼹here，here）

• <强> Bikeshed

  • Bikeshed在W3C和WHATWG都在使用，并且得到了积极维护。
  • Bikeshed完全支持Markdown（很快就会CommonMark）。
  • 编译了Bikeshed规范，因此在标记语法错误（这是主要优势）方面，这适用于CI。
  • 需要在GitHub存储库上设置Travis CI以发布更改，如W3C have done。
  • 可以在本地watcher时使用editing来减少开发周期。
  • 可以使用remotely hosted processor，但它不适用于所有功能（例如单独的biblio文件）。
  • 有一些人从ReSpec迁移到Bikeshed的例子，而不是相反。
  • HTML差异（Bikeshed本身不支持，但在ReSpec中找不到）仍然可以通过手动调整ReSpec Section 5来完成，因为它只是一个简单的curl。
  • 鉴于当前HTML5 spec使用了Bikeshed，它似乎越来越受欢迎。
  • Bikeshed规范示例：here
  • Bikeshed CI示例：here，here，here，here

ReSpec和Bikeshed都有一个功能可以将GitHub问题与规范中的内联问题联系起来，这意味着它们与GitHub很好地配对。发现的所有示例都只使用提交日志进行版本控制。

在社区方面：

• W3C community groups似乎是吸引更广泛受众的好方法，他们建议使用GitHub进行“现代标准制定”（以及ReSpec，尽管该建议可能已过时）。

• {3}}是W3C社区群组的一个非正式版本，它提供了一个现有社区Web Incubator CG和GitHub来讨论与{{{{}}直接相关的主题3}}（这意味着仅对“forum”的“网络平台功能”有用。他们同时使用ReSpec和Bikeshed。

Answer 2

警告：我是ReSpec的原作者（虽然维护现已传递给其他人）。

我认为在一天结束时，很多事情都归结为您的个人偏好。这两个工具都支持您的第一个要求列表。这两个工具都有类似的功能集，有很多重叠（但也有不同的东西），在这两种情况下，文档可能都没有涵盖这一事实。

可能有助于您选择的一些事项：

• ReSpec要求零安装。根据我的经验，这使得相对较新的规范编写的贡献者更容易上手，因为他们可以分配回购并编辑HTML - 刷新浏览器将直接显示编辑。 ReSpec源使用HTML以外的约定，但始终符合HTML。 Bikeshed需要安装Python2并且需要安装，或者使用curl命令到web版本（但我认为这不是很方便）。对于经验丰富的用户来说，这一点没有任何区别。
• ReSpec确实支持批量构建，它附带了一个respec2html工具。您通常应该能够在CI中操作它（否则spec-gen也可以）。
• 据我所知，Publican已经死了。
• 如果您正在制作不适合W3C的规格，则可能需要修补您选择的任何选项。那时你的语言偏好可能是一个因素。
• ReSpec在规格非常大的情况下不会很好（但在大多数情况下都很好）。

总的来说，我认为就是这样。如果您尚未决定，最好的办法可能就是抓住两个相似规格的来源并进行比较以查看您最喜欢的内容，还可以对两者进行一些小编辑，看看对您的预期最方便的内容流程。在一天结束时，不要为此感到痛苦：两种格式都是基于HTML的（如果那是你的话，支持嵌入式Markdown）。如果您需要在它们之间进行转换，则可能需要的时间少于正确彻底的调查所需的时间！

Answer 3

警告：我是Bikeshed的作者。

正如罗宾所说，处理器的选择主要是个人品味。处理器中的大多数差异都很小;据我所知，有两个主要的不同之处需要考虑：

1. Bikeshed将源文档编译为HTML; ReSpec包含在HTML文件中，并在运行中将其重写为更好的HTML。在我看来，这使得ReSpec稍微容易随意使用（无需安装，只需刷新源文档即可查看更改），但Bikeshed更适合生态系统（没有＆＃34;闪存的非ReSpec＆＃39; d内容＆ ＃34;或者＃34;跳转规范＆＃34;当您导航到锚点时）。也就是说，Bikeshed很容易在本地安装，而且很多人都很乐意使用服务器版本。

2. Bikeshed的主要功能之一是其交叉规范链接数据库;它有一个不断增长的（主要以W3C为中心）规范数据库，它定期为定义提供蜘蛛，并且可以很容易地链接到这些定义。这大大改善了W3C规范中的交叉链接，使事情更容易阅读和遵循。但是，如果您不打算链接到W3C规范，或者将它们链接到您，那么这并不是什么大问题。链接＆＃34;本地＆＃34; （在你自己的规范中）在任何一个处理器中都很容易。

Answer 4

所以在Bikeshed vs. ReSpec主题上，有一些想法：

在选择依赖的软件时，项目的技术优势或功能集应该很少成为您的决定因素;当然，除非您绝对需要完成任务并且并非所有竞争者都无法使用这些特定功能。

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

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

也就是说，因为它是一些更具参与性和以网络为中心的规范编辑的杀手级功能，它可以充当磁铁，吸引社区的主要成员。由于这些成员采用Bikeshed并将其用于新规范或将现有规格转换为它，因此增加了该工具的吸引力，从而产生了滚雪球效应。相反，它使ReSpec难以保持其牵引力。有一个反应性维护者，他的工作是编写规范，而他的工具是Bikeshed也有帮助。

总而言之，Bikeshed面前有一个比ReSpec更光明的未来。因此，即使你不需要Bikeshed的额外功能，它的学习曲线也有点陡峭，安装更加复杂，你可能仍然只想选择它，因为它有更多的牵引力，这是以下代码：

• 它将会更长，
• 错误应该更快修复，
• 它应该更快地改进，
• 它应该更稳定，
• 它可能会为你的作品添加一些贴面，因为你正在使用酷孩子的工具。

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

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