1

我对 Web API 描述语言的世界还很陌生，并且刚刚开始为我们的 JAX-RS 应用程序研究 Swagger、API 蓝图和 RAML。它们看起来都很棒，但我有一个问题。

我的理解是自上而下的方法，你首先设计你的 API，生成一个漂亮的 HTML 文档，可能还有一个模拟，然后开始编码。

但是，如果在实施过程中由于某些原因最终不得不更改 API 的签名，例如更改响应主体模型，该怎么办？我的意思是在这种情况下，您的 API 规范需要更改，并且您必须手动编辑您的 API 规范以使其与您的代码保持同步，因为似乎没有成熟的库可以从源代码生成 API 规范。（我已经为 Swagger 和 RAML 测试了此类库，但没有测试 APIB，因为我找不到 JAX-RS 源 APIB 转换库。）在上述情况下，您如何处理它？

您是手动编辑 API Spec 还是使用某些库自动进行编辑？如果是后者，你能告诉我图书馆的名字吗？

4

2 回答 2

2

如果您想确保您的 API 描述和文档同步，请务必查看Dredd。

Dredd 的标语是：

不再有过时的 API 文档

Dredd 是一个 API 测试框架，它使用 API 蓝图并针对 API 后端对其进行测试。你可以很容易地把它变成你的测试套件的一部分，这样它就可以成为整个开发生命周期的一部分。从设计到本地 TDD、持续集成甚至实时 API 的部署后验证。

因此，我建议在设计过程中手动编辑/编写 API 描述，然后对其进行测试，而不是从代码中生成文档。

免责声明：我是 Dredd 维护者

于 2015-04-16T05:58:02.093 回答
0

对于 RAML，您可以查看abao。它是一个命令行实用程序，用于检查 RAML 规范是否与后端实现匹配。我自己没用过，不过好像和 Dredd 一样。

于 2015-10-02T09:56:08.220 回答