Unfortunately, Darrel's answer is technically correct, but is hocus-pocus in the real world. It's based on the ideal that only some agree on and even if you were very careful about it, the chances are that for some reason outside your control, you can't conform exactly.
Even if you could, other developers that might have to use your API may not care or know the details of RESTful patterns... Remember that the point of creating the API is to make it easy for others to use it and good documentation is a must.
Achim's point about the WADL is good however. Because it exists, we should be able to create a basic tool for generating documentation of the API.
Some folks have taken this route, and an XSL stylesheet has been developed to do the transform: https://wadl.dev.java.net/
虽然我不确定它是否完全满足您的需求，但请查看 enunciate。对于各种 Web 服务架构来说，它似乎是一个很好的文档生成器。
编辑 Enunciate 可在 github 保护下使用
Although i'm not sure it will totally fit your needs, take a look at enunciate. It seems like a good documentation generator for various web-services architectures.
you might be interested in Jersey's ability to provide so called WADL description for all published resources in XML format at runtime (generated automatically from annotations). This should be containing already what you need for basic documentation. Further you might be able to add additional JavaDoc, though that requires more configuration.
Darrel's answer is exactly right. The kind of description must not be given to clients of a REST API because it will lead the client developer to couple the implementation of the client to the current implementation of the service. This is what REST's hypermedia constraint aims to avoid.
You might still develop an API that is described that way, but you should be aware that the resulting system will not implement the REST architectural style and will therefore not have the properties (esp. evolvability) guaranteed by REST.
Your interface might still be a better solution than RPC for example. But be aware what it is that you are building.
您可能会发现 rest-tool 很有用。 它遵循与语言无关的方法来编写 RESTful API 的规范、模拟实现和自动化单元测试。
您只能使用它来记录您的 API，但该规范可以立即用于保证实际服务实施的质量。
如果您的服务尚未完全实现，但例如应该由 Web 前端应用程序使用， rest-tool 提供基于服务描述的即时模拟。内容模式验证（JSON 模式）也可以轻松添加到文档旁边并供单元测试使用。
You might find rest-tool useful. It follows language agnostic approach to write specification, mock implementation and automated unit-testing for RESTful APIs.
You can use it only for documenting your APIs, but this specification can immediately be used to quality assure the implementation of the real services.
If your services are not fully implemented yet, but for example should be used by a web frontend application, rest-tool provides instant mocking based on the service description. content schema validation (JSON schema) also can be easily added beside the documentation as well as used by the unit tests.
I hate to be the bearer of bad news, but if you feel the need to document the things you listed, then you probably did not create a REST interface.
REST interfaces are documented by identifying a single root URL and then by describing the media type of the representation that is returned from that URL and all the media types that can be accessed via links in that representation.
What media types are you using?
Also, put a link to RFC2616 in your docs. That should explain to any consumer how to interact with your service.
发布评论
评论（7）
Swagger 是一个不错的选择。它是 GitHub 上的一个项目，具有 Maven 集成和大量其他选项以保持灵活性。
集成指南：https://github.com/swagger-api/swagger-core/wiki< /a>
更多信息：http://swagger.io/
Swagger is a beautiful option. It's a project on GitHub, has Maven integration and loads of other options to keep it flexible.
Integration guide: https://github.com/swagger-api/swagger-core/wiki
More Information: http://swagger.io/
不幸的是，达雷尔的答案在技术上是正确的，但在现实世界中却是骗人的。它基于只有一些人同意的理想，即使你对此非常小心，也很可能由于某些超出你控制范围的原因，你无法完全遵守。
即使您可以，其他可能需要使用您的 API 的开发人员也可能不关心或不了解 RESTful 模式的详细信息...请记住，创建 API 的目的是让其他人轻松使用它，而良好的文档是必须。
不过，Achim 关于 WADL 的观点很好。因为它存在，我们应该能够创建一个用于生成 API 文档的基本工具。
有些人已经采取了这条路线，并且已经开发了 XSL 样式表来进行转换：
https://wadl.dev.java.net/
Unfortunately, Darrel's answer is technically correct, but is hocus-pocus in the real world. It's based on the ideal that only some agree on and even if you were very careful about it, the chances are that for some reason outside your control, you can't conform exactly.
Even if you could, other developers that might have to use your API may not care or know the details of RESTful patterns... Remember that the point of creating the API is to make it easy for others to use it and good documentation is a must.
Achim's point about the WADL is good however. Because it exists, we should be able to create a basic tool for generating documentation of the API.
Some folks have taken this route, and an XSL stylesheet has been developed to do the transform:
https://wadl.dev.java.net/
虽然我不确定它是否完全满足您的需求，但请查看 enunciate。对于各种 Web 服务架构来说，它似乎是一个很好的文档生成器。
编辑 Enunciate 可在 github 保护下使用
Although i'm not sure it will totally fit your needs, take a look at enunciate. It seems like a good documentation generator for various web-services architectures.
EDIT Enunciate is available under github umbrella
您可能对 Jersey 在运行时以 XML 格式为所有已发布资源提供所谓的 WADL 描述（从注释自动生成）的能力感兴趣。这应该已经包含您所需的基本文档。此外，您也许可以添加额外的 JavaDoc，但这需要更多配置。
请看这里：
https://jersey.java.net/documentation/latest/wadl.html
you might be interested in Jersey's ability to provide so called WADL description for all published resources in XML format at runtime (generated automatically from annotations). This should be containing already what you need for basic documentation. Further you might be able to add additional JavaDoc, though that requires more configuration.
Please look here:
https://jersey.java.net/documentation/latest/wadl.html
达雷尔的回答完全正确。不得向 REST API 的客户端提供此类描述，因为这会导致客户端开发人员将客户端的实现与服务的当前实现耦合起来。这正是 REST 的超媒体约束旨在避免的。
您可能仍会开发以这种方式描述的 API，但您应该意识到生成的系统将不会实现 REST 架构风格，因此不会具有 REST 保证的属性（尤其是可演化性）。
例如，您的接口可能仍然是比 RPC 更好的解决方案。但请注意您正在构建的是什么。
扬
Darrel's answer is exactly right. The kind of description must not be given to clients of a REST API because it will lead the client developer to couple the implementation of the client to the current implementation of the service. This is what REST's hypermedia constraint aims to avoid.
You might still develop an API that is described that way, but you should be aware that the resulting system will not implement the REST architectural style and will therefore not have the properties (esp. evolvability) guaranteed by REST.
Your interface might still be a better solution than RPC for example. But be aware what it is that you are building.
Jan
您可能会发现 rest-tool 很有用。
它遵循与语言无关的方法来编写 RESTful API 的规范、模拟实现和自动化单元测试。
您只能使用它来记录您的 API，但该规范可以立即用于保证实际服务实施的质量。
如果您的服务尚未完全实现，但例如应该由 Web 前端应用程序使用， rest-tool 提供基于服务描述的即时模拟。内容模式验证（JSON 模式）也可以轻松添加到文档旁边并供单元测试使用。
You might find rest-tool useful.
It follows language agnostic approach to write specification, mock implementation and automated unit-testing for RESTful APIs.
You can use it only for documenting your APIs, but this specification can immediately be used to quality assure the implementation of the real services.
If your services are not fully implemented yet, but for example should be used by a web frontend application, rest-tool provides instant mocking based on the service description. content schema validation (JSON schema) also can be easily added beside the documentation as well as used by the unit tests.
我讨厌传递坏消息，但如果您觉得需要记录您列出的内容，那么您可能没有创建 REST 接口。
REST 接口通过识别单个根 URL，然后描述从该 URL 返回的表示的媒体类型以及可以通过该表示中的链接访问的所有媒体类型来记录。
您使用什么媒体类型？
另外，请在您的文档中放置一个指向 RFC2616 的链接。这应该向任何消费者解释如何与您的服务进行交互。
I hate to be the bearer of bad news, but if you feel the need to document the things you listed, then you probably did not create a REST interface.
REST interfaces are documented by identifying a single root URL and then by describing the media type of the representation that is returned from that URL and all the media types that can be accessed via links in that representation.
What media types are you using?
Also, put a link to RFC2616 in your docs. That should explain to any consumer how to interact with your service.