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

Question

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

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

如果有人使用Java，这一切都很顺利。我只是给它们带有InstanceWithXmlRootElementAnnotation类的Jar并告诉他们发送它（是的，还有一些工作，忽略那些细节）。

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

Answer 1

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

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

Answer 3

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

Answer 4

也尝试enunciate，它解析服务类的javadoc和JAX-RS注释以生成文档：

http://enunciate.codehaus.org/

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

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

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