"A REST API should spend almost all of its descriptive
effort in defining the media type(s) used for representing
resources and driving application state, or in defining
extended relation names and/or hypertext-enabled mark-up
for existing standard media types."
"A REST API should spend almost all of its descriptive
effort in defining the media type(s) used for representing
resources and driving application state, or in defining
extended relation names and/or hypertext-enabled mark-up
for existing standard media types."
Self-descriptiveness is one of the benefits of REST.
虽然不是 REST，但我使用 Sphinx 来记录 XML-RPC API，其中包含 API 参考和教程。 Sphinx 在 ReStructuredText 中添加了一些方便的指令，以获得几乎您所要求的内容：格式化的 ReStructuredText 集合-Sphinx 转换为 HTML 和 PDF 的文本文件，包含索引和目录。 Sphinx 易于使用且文档齐全；我认为，说十分钟左右就可以开始使用并不夸张。
While not REST, I used Sphinx to document an XML-RPC API that consisted of an API reference and a tutorial. Sphinx adds some handy directives to ReStructuredText to get pretty much what you asked for: a collection of ReStructuredText formatted-text files that Sphinx turns into HTML and PDFs, complete with an index and table of contents. Sphinx is easy to use and well-documented; I don't think it would be an exaggeration to say you could get started with it in about ten minutes.
一些 RESTful 系统实际上能够编写自己的 API。看一下 RESTx，它就是这样做的：您编写组件，然后通过发送参数来创建新的 Web 服务将这些组件发送到服务器（作为 JSON 或通过 Web 表单）。然后您将获得这些参数的 URI。访问它会调用带有参数的组件，然后您检索结果。
无论如何，组件以及创建的 RESTful Web 服务都会获得自动生成的文档，该文档是可浏览的，并且可以以 HTML 或 JSON 格式检索。
Some RESTful systems are actually able to write their own API. Have a look at RESTx, which does just that: You write your components and then create new web services by sending parameters for those components to the server (either as JSON or via a web form). You then get a URI back for those parameters. Accessing it calls the component with the parameters and you retrieve the results.
At any rate, the components as well as the created RESTful web services get an automatically generated documentation, which is browseable and can be retrieved either in HTML or JSON format.
发布评论
评论（3）
根据 Roy 的说法：
自我描述性是REST 的好处之一。
According to Roy:
Self-descriptiveness is one of the benefits of REST.
虽然不是 REST，但我使用 Sphinx 来记录 XML-RPC API，其中包含 API 参考和教程。 Sphinx 在 ReStructuredText 中添加了一些方便的指令，以获得几乎您所要求的内容：格式化的 ReStructuredText 集合-Sphinx 转换为 HTML 和 PDF 的文本文件，包含索引和目录。 Sphinx 易于使用且文档齐全；我认为，说十分钟左右就可以开始使用并不夸张。
While not REST, I used Sphinx to document an XML-RPC API that consisted of an API reference and a tutorial. Sphinx adds some handy directives to ReStructuredText to get pretty much what you asked for: a collection of ReStructuredText formatted-text files that Sphinx turns into HTML and PDFs, complete with an index and table of contents. Sphinx is easy to use and well-documented; I don't think it would be an exaggeration to say you could get started with it in about ten minutes.
一些 RESTful 系统实际上能够编写自己的 API。看一下 RESTx，它就是这样做的：您编写组件，然后通过发送参数来创建新的 Web 服务将这些组件发送到服务器（作为 JSON 或通过 Web 表单）。然后您将获得这些参数的 URI。访问它会调用带有参数的组件，然后您检索结果。
无论如何，组件以及创建的 RESTful Web 服务都会获得自动生成的文档，该文档是可浏览的，并且可以以 HTML 或 JSON 格式检索。
Some RESTful systems are actually able to write their own API. Have a look at RESTx, which does just that: You write your components and then create new web services by sending parameters for those components to the server (either as JSON or via a web form). You then get a URI back for those parameters. Accessing it calls the component with the parameters and you retrieve the results.
At any rate, the components as well as the created RESTful web services get an automatically generated documentation, which is browseable and can be retrieved either in HTML or JSON format.