我用Java Jersey（和JAXB）编写了一个相当广泛的REST API。我也使用维基书写了文档，但这是一个完全手动的过程，非常容易出错，特别是当我们需要进行修改时，人们往往会忘记更新维基。
从观察其他大多数REST API来看，它们也是手动创建其文档。但我想知道是否有好的解决方案。
需要为每个端点记录的内容包括：
然后当然还有一些全局通用的东西，比如：
这些通用的东西描述一次就可以了，不需要自动化，但对于Web服务方法本身，自动化似乎非常有必要。
我考虑过使用注解，并编写一个生成XML的小程序，然后使用XSLT生成实际的HTML文档。使用自定义的XDoclet是否更合理？
Swagger是一个很棒的选择，它是GitHub上的一个项目，具有Maven集成和许多其他选项，以保持灵活性。
集成指南：https://github.com/swagger-api/swagger-core/wiki
更多信息：http://swagger.io/
很遗憾，Darrel的答案在技术上是正确的，但在现实世界中却是虚假的。它基于只有一些人同意的理想，并且即使你非常小心，机会也是你无法完全符合。
即使你可以，可能需要使用你的API的其他开发人员可能不关心或不知道RESTful模式的细节...请记住，创建API的重点是使其易于他人使用，而良好的文档则是必须的。
Achim关于WADL（Web应用程序描述语言）的观点是好的。因为它存在，我们应该能够创建一个基本工具来生成API的文档。
一些人已经采取了这种做法，并开发了XSL样式表进行转换： https://wadl.dev.java.net/
Stackoverflow.com，你需要对该网站的结构和预期用途有深入了解。你不能从根URL开始"探索它"，也不应指望"文本/ HTML"这种媒体类型提供太多帮助。你最终只能手动浏览它，以创建一个好的API文档提供的地图。 - Alexander Ljungberg您可能对Jersey提供的所谓“WADL”感兴趣，它能在运行时以XML格式为所有已发布资源提供描述（从注释中自动生成）。这应该已经包含了基本文档所需的内容。此外，您可能还可以添加其他的JavaDoc，但这需要更多的配置。
请查看这里：https://jersey.java.net/documentation/latest/wadl.html
达瑞尔的回答完全正确。不应该向REST API的客户端提供这种类型的描述，因为它会导致客户端开发人员将客户端的实现与服务的当前实现耦合在一起。这就是REST超媒体约束的目的所在。
您仍然可以开发一个以此方式描述的API，但您应该意识到，由此产生的系统将不会实现REST架构风格，因此不具备REST所保证的属性（尤其是可演化性）。
您的接口可能仍然比RPC等更好的解决方案。但请注意您正在构建的内容。
扬
不想打击你，但如果你觉得需要记录你列举的事情，那么很可能你并没有创建REST接口。
REST接口通过确定单个根URL并描述从该URL返回的表示形式的媒体类型及可以通过表示形式中链接访问的所有媒体类型来进行文档化。
你使用了哪些媒体类型？
此外，在你的文档中加入RFC2616的链接，这将向任何使用者解释如何与你的服务交互。