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

Question

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

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

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

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

Answer 1

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.
 */

Answer 2

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

Answer 3

Also try enunciate, it parses the javadoc and JAX-RS annotations of your service classes to generate documentation:

http://enunciate.codehaus.org/

Here is some example documentation generated by enunciate:

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

There is a maven plugin that works well.It also generates client libraries in various languages as well as sample xml for xml based services. It now supports swagger documentation as well.

Answer 4

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