java - 如何自动化 REST API 的文档（泽西岛实现）

Question

我使用 Java Jersey（和 JAXB）编写了一个非常广泛的 REST API。我也使用 Wiki 编写了文档，但这是一个完全手动的过程，非常容易出错，尤其是当我们需要进行修改时，人们往往会忘记更新 wiki。

环顾四周，大多数其他 REST API 也在手动创建他们的文档。但我想知道是否有一个很好的解决方案。

需要为每个端点记录的事情是：

然后当然有一些通用的东西是全球性的，例如

这些一般的东西可以描述一次并且不需要自动化，但是对于 Web 服务方法本身来说，自动化它似乎是非常可取的。

我考虑过可能使用注释，并编写一个生成 XML 的小程序，然后是一个 XSLT，它应该生成 HTML 中的实际文档。使用自定义 XDoclet 是否更有意义？

score 42 · Accepted Answer

Swagger是一个不错的选择。这是 GitHub 上的一个项目，具有 Maven 集成和许多其他选项以保持其灵活性。

在此处输入图像描述

score 22 · Accepted Answer

不幸的是，达雷尔的回答在技术上是正确的，但在现实世界中却是个骗局。它基于只有一些人同意的理想，即使您对此非常小心，也有可能由于某些超出您控制范围的原因，您无法完全符合。

即使您可以，其他可能不得不使用您的 API 的开发人员可能并不关心或不知道 RESTful 模式的细节......请记住，创建 API 的目的是让其他人更容易使用它，好的文档是必须。

然而，Achim 关于 WADL 的观点很好。因为它存在，我们应该能够创建一个用于生成 API 文档的基本工具。

有些人采用了这条路线，并且开发了一个 XSL 样式表来进行转换： https ://wadl.dev.java.net/

score 16 · Accepted Answer

虽然我不确定它是否完全符合您的需求，但请看一下enunciate。对于各种 Web 服务架构，它似乎是一个很好的文档生成器。

EDIT Enunciate 在 github 保护伞下可用

score 8 · Accepted Answer

您可能对 Jersey 在运行时以 XML 格式为所有已发布资源提供所谓的WADL描述的能力感兴趣（从注释自动生成）。这应该已经包含基本文档所需的内容。此外，您可能还可以添加额外的 JavaDoc，但这需要更多配置。

score 2 · Accepted Answer

达雷尔的回答完全正确。这种描述不能提供给 REST API 的客户端，因为它会导致客户端开发人员将客户端的实现与服务的当前实现耦合。这是 REST 的超媒体约束旨在避免的。

您可能仍会开发以这种方式描述的 API，但您应该意识到生成的系统不会实现 REST 架构风格，因此不会具有 REST 所保证的属性（尤其是可进化性）。

例如，您的接口可能仍然是比 RPC 更好的解决方案。但请注意您正在构建的是什么。

简

score 0 · Accepted Answer

您可能会发现rest-tool很有用。它遵循与语言无关的方法来为 RESTful API 编写规范、模拟实现和自动化单元测试。

您只能将其用于记录您的 API，但此规范可立即用于质量保证实际服务的实施。

如果您的服务尚未完全实现，但例如应该由 Web 前端应用程序使用，rest-tool会根据服务描述提供即时模拟。内容模式验证（JSON 模式）也可以很容易地添加到文档旁边以及由单元测试使用。

score -1 · Accepted Answer

我讨厌成为坏消息的承担者，但是如果您觉得需要记录您列出的内容，那么您可能没有创建 REST 接口。

REST 接口通过识别单个根 URL，然后通过描述从该 URL 返回的表示的媒体类型以及可以通过该表示中的链接访问的所有媒体类型来记录。

您使用什么媒体类型？

此外，在您的文档中添加一个指向RFC2616的链接。这应该向任何消费者解释如何与您的服务进行交互。

7 回答 7