如何为使用 JSON JAXB 绑定的 Jersey REST API 生成文档？答案

【问题标题】：How can I generate documentation for my Jersey REST API that uses JSON JAXB binding?如何为使用 JSON JAXB 绑定的 Jersey REST API 生成文档？
【发布时间】：2013-09-14 12:34:46
【问题描述】：

现在我已经知道how to use JAXB generate JSON 我可以在我的服务器上请求/响应它，我想知道如何为不使用 Java 的人生成有用的文档。我的服务器代码如下所示：

@POST
@Path("apath")
@Consumes(MediaType.APPLICATION_JSON)
public String postAPath(InstanceWithXmlRootElementAnnotation instanceWithXmlRootElementAnnotation) {

如果有人使用 Java，那就太好了。我只是给他们一个带有InstanceWithXmlRootElementAnnotation 类的Jar，然后告诉他们把它发送过来（是的，还有一些工作，忽略这些细节）。

如果他们使用其他语言，我不知道我应该如何告诉他们有效负载的格式，以及如果服务器返回 InstanceWithXmlRootElementAnnotation 会发生什么。如何生成解释 JSON 有效负载预期格式的文档？

【问题讨论】：

标签： java json jaxb jersey jersey-1.0

【解决方案1】：

是的，这正是Swagger 的用途。查看github 了解有关它如何与 JAX-RS 集成的详细信息

【讨论】：

【解决方案2】：

Swagger 使用的注释可能会让您与其他功能注释混淆..

使用APIDOC 将功能注释和文档很好地分开。它看起来像每个方法上方的普通文档。例如：

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

【讨论】：

【解决方案3】：

Swagger 是一个不错的选择（根据 @fehguy），您还应该查看 enunciate 并查看最适合您的应用程序的方法...

【讨论】：

请注意，enunciate 与 java 8 不兼容。

【解决方案4】：

还可以尝试发音，它会解析服务类的 javadoc 和 JAX-RS 注释以生成文档：

http://enunciate.codehaus.org/

以下是 enunciate 生成的一些示例文档：

https://repository.sonatype.org/nexus-restlet1x-plugin/default/docs/index.html

有一个运行良好的 maven 插件。它还生成各种语言的客户端库以及基于 xml 的服务的示例 xml。它现在也支持 swagger 文档。

【讨论】：

仅供参考，示例文档链接已损坏。