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

Question

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

要求(对大多数人来说必须是共同的):

• 规范历史:我们希望能够引用规范的先前版本.
• 版本控制:我们希望将规范存储在版本控制中,以便我们可以针对我们的代码库标记版本并将其与相关内容一起存储
• 问题:我们希望允许社区提交问题.
• 社区/联盟:我们希望与更广泛的社区分享规范,以获得对我们方法的验证.端点验证器.
• 格式/工具:我们希望使用易于编辑的格式,并且可以将其发布为易于理解的格式.
• 潜在的批准:如果它有用,那么创建一个标准,以便有更广泛采用的途径将是一件好事.

通过一些研究,有一些相关的标准组织:

• IETF(Internet工程任务组):主要使用基于文本的RFC格式,但似乎有一些不错的跟踪工具.通常对于较低级别的标准(例如TCP),尽管它们也创建了更高级别的标准.

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

• WHATWG(Web超文本应用技术工作组):一个似乎主要关注 HTML5的组,因此与REST API规范的相关性较低.

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

我在网上看了几个例子,并注意到方法的不同之处:

• YAML:规范历史,在GitHub中版本化,GitHub上的问题,没有明显的从属关系,使用 DocBook.

• JSON-LD:规范历史,在GitHub中版本化,关于GitHub, W3C从属关系的问题,使用 ReSpec(也在 GitHub上).

• JSON API:规范历史,在GitHub中版本化,GitHub上的问题,没有明显的从属关系,似乎使用Jekyll和一些自定义模板.

• JMAP:在GitHub中版本化,GitHub上的问题,没有明显的联系,似乎使用markdown和一些自定义模板.

• HTML 5(W3C):在GitHub中版本化,GitHub上的问题, W3C从属关系,使用 Bikeshed.

• HTML 5(WHATWG):在GitHub中进行版本化,GitHub上的问题, WHATWG从属关系,使用"专有语言,然后将其后处理成HTML"(源代码).

• JSON Schema:使用IETF工具进行版本化, GitHub上的问题, IETF从属关系,使用 IETF RFC格式.

• CSS 3:规范历史,在Mercurial中版本化,内联规范, W3C从属关系,使用 Bikeshed.

对于REST API,我们应遵循哪种方法？各有哪些优缺点？

Answer 1

鉴于它是基于 REST 的 API，W3C 是最相关的。WHATWG 过于关注 HTML，IETF 会导致规范可读性较差，并且 OASIS 可能过于晦涩难懂。

\n

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

\n

如果选择 W3C，则必须遵循Pubrules （有一个新的W3C pubrules 验证器，可通过 npm 和此处访问）。目前流行两种主要格式/工具，均受 W3C 工具的支持，如下所述：

\n

\n

ReSpec and Bikeshed: Since W3C "pubrules" markup can prove repetitive and at times hard to get right, many tools have been developed to assist people in producing it \xe2\x80\x94 these are the two main ones. ReSpec documents are essentially valid HTML with some extra configuration that a JS library turns into the real thing; Bikeshed is a Python preprocessor that can apply to HTML but is more often used in Markdown mode.

\n

\n

N.B. Anolis, an older preprocessor that preceded ReSpec and Bikeshed, has been declared dead by it\'s author.

\n

W3C is currently undergoing a process of modernisation. A new W3C project named Echidna (based in GitHub) supports both ReSpec and Bikeshed automated publishing, though the latter has only recently been implemented, and it currently only works inside the W3C.

\n

Using either of the above tools will allow the standard to be indexed in specref.org (the database of bibliographical references that W3C specifications rely upon).

\n

Notes on each of these options:

\n

\n

• ReSpec

  \n
  \n
  • ReSpec is in use at the W3C and actively maintained.
  \n
  • ReSpec apparently does support Markdown, but the feature is undocumented.
  \n
  • Spec Generator seems in common use in W3C for ReSpec CI, and can be accessed outside the W3C (it used to be internal).
  \n
  • In terms of CI alternatives:\n
    \n
    • Echidna is a new official recommendation for ReSpec CI, however it currently only works inside the W3C.
    \n
    • Publican is a GitHub hook listener that generates specs written to be parsed by ReSpec or Bikeshed. Hard to tell the status of the project though, as it appears to be discontinued (Robin originally created ReSpec, and did lots of work for webplatform.org, but the project may have since changed direction). Likely better to use actual Bikeshed for Bikeshed CI. It also runs in Docker (see gist).
    \n
    \n
  \n
  • There are various articles discussing the use of ReSpec with GitHub, and the publishing process.
  \n
  • Some say ReSpec is more accessible.
  \n
  • Examples of ReSpec specs: here, here, here, here
  \n
  • Examples of ReSpec CI: here (Echidna here, here)
  \n
  \n
\n

• Bikeshed

  \n
  \n
  • Bikeshed is in use at both the W3C and WHATWG, and is actively maintained.
  \n
  • Bikeshed fully supports Markdown (and soon CommonMark).
  \n
  • Bikeshed specs are compiled, so this works well for CI in terms of flagging syntax error (it\'s main advantage).
  \n
  • Need to set up Travis CI on the GitHub repo to publish changes, as the W3C have done.
  \n
  • Can use a watcher when editing locally to reduce dev cycle.
  \n
  • Can use a remotely hosted processor, but it won\'t work with all features (e.g. the separate biblio file).
  \n
  • There are a few examples of people migrating from ReSpec to Bikeshed, not the other way around.
  \n
  • HTML diff (not natively supported in Bikeshed, but found in ReSpec) can still be done by manually adapting ReSpec Section 5, as it\'s just a simple curl.
  \n
  • Given the use of Bikeshed for the current HTML5 spec, it would appear to be gaining popularity.
  \n
  • Examples of Bikeshed specs: here
  \n
  • Examples of Bikeshed CI: here, here, here, here
  \n
  \n
\n

\n

Both ReSpec and Bikeshed have a feature to link GitHub issues to inline issues in the spec, which mean they pair well with GitHub. All examples found just use commit logs for versioning.

\n

In terms of community:

\n

\n

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

  \n
\n

• Web孵化器 CG是 W3C 社区组的一个更加非正式的版本，它提供了一个现有的社区、GitHub和论坛来讨论与“Web 平台”直接相关的主题（这意味着仅对“Web 平台功能”有用）在浏览器或类似的用户代理中实现“）。他们同时使用 ReSpec 和 Bikeshed。

  \n
\n

\n