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

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

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

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

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

Answer 1

Swagger是一个不错的选择（根据@fehguy），你也应该看看发音 ，看看什么最适合你的应用程序……

Answer 2

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

Answer 3

Swagger使用注释可能会让您与其他function注释混淆。

使用APIDOC在function注释和文档之间进行良好的分离。 它看起来像每个方法上面的常规文档。 例如：

 /** * @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 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文档。