Java 如何自动化 REST API 的文档编制（泽西岛实现）

How to automate documentation of a REST API (Jersey Implementation)

提问by Alan Mc Kernan

I have written a pretty extensive REST API using Java Jersey (and JAXB). I have also written the documentation using a Wiki, but its been a totally manual process, which is very error-prone, especially when we need to make modifications, people tend to forget to update the wiki.

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

From looking around, most other REST API's are also manually creating their documentation. But I'm wondering if theres maybe a good solution to this.

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

The kind of things which need to be documented for each endpoint are:

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

• Service Name
• Category
• URI
• Parameter
• Parameter Types
• Response Types
• Response Type Schema (XSD)
• Sample requests and responses
• Request type (Get/Put/Post/Delete)
• Description
• Error codes which may be returned

• 服务名称
• 类别
• URI
• 范围
• 参数类型
• 响应类型
• 响应类型架构 (XSD)
• 示例请求和响应
• 请求类型（获取/放置/发布/删除）
• 描述
• 可能返回的错误代码

And then of course there are some general things which are global such as

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

• Security
• Overview of REST
• Error handling
• Etc

• 安全
• REST 概述
• 错误处理
• 等等

These general things are fine to describe once and don't need to be automated, but for the web service methods themselves it seems highly desirable to automate it.

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

I've thought of maybe using annotations, and writing a small program which generates XML, and then an XSLT which should generate the actual documentation in HTML. Does it make more sense to use custom XDoclet?

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

回答by Darrel Miller

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 接口。

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.

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

What media types are you using?

您使用什么媒体类型？

Also, put a link to RFC2616in your docs. That should explain to any consumer how to interact with your service.

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

回答by Darrel Miller

you might be interested in Jersey's ability to provide so called WADLdescription 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.

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

Please look here: https://jersey.java.net/documentation/latest/wadl.html

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

回答by Jan Algermissen

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.

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

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.

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

Your interface might still be a better solution than RPC for example. But be aware what it is that you are building.

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

Jan

简

回答by Brill Pappin

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.

即使可以，其他可能不得不使用您的 API 的开发人员可能并不关心或了解 RESTful 模式的详细信息……请记住，创建 API 的目的是让其他人更容易使用它，而好的文档是一个必须。

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.

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

Some folks have taken this route, and an XSL stylesheet has been developed to do the transform: https://wadl.dev.java.net/

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

回答by Riduidel

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.

尽管我不确定它是否完全符合您的需求，但请查看enunciate。它似乎是适用于各种 Web 服务架构的良好文档生成器。

EDITEnunciate is available under github umbrella

EDITEnunciate 在 github 伞下可用

回答by Webnet

Swaggeris a beautiful option. It's a project on GitHub, has Maven integration and loads of other options to keep it flexible.

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

Integration guide: https://github.com/swagger-api/swagger-core/wiki

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

More Information: http://swagger.io/

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

回答by tombenke

You might find rest-tooluseful. It follows language agnostic approach to write specification, mock implementation and automated unit-testing for RESTful APIs.

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

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.

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

If your services are not fully implemented yet, but for example should be used by a web frontend application, rest-toolprovides 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.

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