如何自动化REST API的文档（Jersey实现）

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

从环顾四周，大多数其他REST API也都是手动创build文档。但是我想知道如果这可能是一个很好的解决scheme。

需要为每个端点logging的事物types是：

当然，还有一些一般的东西是全球性的

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

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

任何帮助将非常感激，艾伦

Swagger是一个很好的select。这是GitHub上的一个项目，有Maven集成和其他一些选项来保持它的灵活性。

集成指南： https ： //github.com/swagger-api/swagger-core/wiki

更多信息： http : //swagger.io/

在这里输入图像说明

不幸的是，达雷尔的答案在技术上是正确的，但在现实世界中却是焦点。它是基于只有一些人认同的理想，即使你非常小心，也有可能出于某种原因在你的控制之外，你不能完全符合。

即使你可以，其他可能不得不使用你的API的开发者可能不关心或者不知道RESTful模式的细节……记住，创buildAPI的重点是让别人很容易使用它，好的文档是一个必须。

Achim关于WADL的观点是好的。因为它存在，所以我们应该能够创build一个生成API文档的基本工具。

有些人已经采取了这样的路线，并且已经开发了一个XSL样式表来完成这个转换： https ： //wadl.dev.java.net/

虽然我不确定它会完全适合您的需求，但请看一下发音。对于各种Web服务体系结构来说，它似乎是一个很好的文档生成器。

编辑阐明是可用的github伞下

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

请看这里： https : //jersey.java.net/documentation/latest/wadl.html

达雷尔的回答是完全正确的。这种描述不能给予REST API的客户端，因为它会引导客户端开发者将客户端的实现与服务的当前实现结合起来。这就是REST的超媒体约束所要避免的。

您仍然可以开发一种以这种方式描述的API，但是您应该意识到由此产生的系统将不会实现REST架构风格，因此不会具有REST保证的属性（特别是可演化性）。

例如，您的界面可能仍然是比RPC更好的解决scheme。但请注意你正在build造的是什么。

一月

我讨厌成为坏消息的持有者，但是如果你觉得需要logging你列出的东西，那么你可能没有创build一个REST接口。

通过标识单个根URL并通过描述从该URL返回的表示的媒体types以及可以通过该表示中的链接访问的所有媒体types来loggingREST接口。

你使用什么媒体types？

另外，在你的文档中添加一个到RFC2616的链接。这应该向任何消费者解释如何与您的服务互动。

你可能会发现rest-tool很有用。它遵循语言不可知方法来编写规范，模拟实现和RESTful API的自动化unit testing。

您只能用它来logging您的API，但是这个规范可以立即用于质量保证真实服务的实现。

如果您的服务尚未完全实现，但是例如应由Web前端应用程序使用，则rest-tool会根据服务描述提供即时模拟。内容模式validation（JSON模式）也可以轻松添加到文档旁边，也可以在unit testing中使用。