我使用Java Jersey(和JAXB)编写了一个非常广泛的REST API.我还使用Wiki编写了文档,但它是一个完全手动的过程,非常容易出错,特别是当我们需要进行修改时,人们往往忘记更新wiki.

从四处查看,大多数其他REST API也可以手动创建文档.但我想知道这是否可能是一个很好的解决方案.

需要为每个端点记录的事物类型是：

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

然后当然有一些全球性的事情,如

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

这些一般的东西可以描述一次并且不需要自动化,但对于Web服务方法本身来说,似乎非常希望自动化它.

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

解决方法:

Swagger是一个很好的选择.它是GitHub上的一个项目,具有Maven集成和其他选项以保持其灵活性.

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

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