问题描述
我已经写了使用Java泽西（和JAXB）一pretty广泛的REST API。我也写使用维基的文件，但它是一个完全人工的过程，这是非常容易出错，尤其是当我们需要进行修改，人们往往忘记更新维基。
I have written a pretty extensive REST API using Java Jersey (and JAXB). I have also written the documentation using a Wiki, but its been a totally manual process, which is very error-prone, especially when we need to make modifications, people tend to forget to update the wiki.
环视，其他大部分REST API的也手动创建自己的文档。但我不知道是否theres也许一个很好的解决了这一点。
From looking around, most other REST API's are also manually creating their documentation. But I'm wondering if theres maybe a good solution to this.
那种事情需要记录每个端点分别是：
The kind of things which need to be documented for each endpoint are:
- 服务名称
- 类别
- URI
- 参数
- 参数类型
- 响应类型
- 响应类型架构（XSD）
- 示例请求和响应
- 请求类型（GET /认沽/后/删除）
- 说明
- 错误codeS可能会返回
然后当然有一些普遍的东西是全球性，如
And then of course there are some general things which are global such as
- 安全
- REST概述
- 错误处理
- 等
这些东西一般是细描述一次，不需要进行自动化，但对web服务方法本身似乎非常希望自动执行它。
These general things are fine to describe once and don't need to be automated, but for the web service methods themselves it seems highly desirable to automate it.
我想也许使用注释，写一个小程序生成的XML，然后应生成HTML的实际文档的XSLT。是否更有意义使用自定义的XDoclet？
I've thought of maybe using annotations, and writing a small program which generates XML, and then an XSLT which should generate the actual documentation in HTML. Does it make more sense to use custom XDoclet?
任何帮助将是非常美联社preciated，
阿伦
Any help would be much appreciated,Alan
推荐答案
是一个美丽的选择。这是在GitHub上的一个项目，有Maven的集成和其他选项负荷保持它的灵活性。
Swagger is a beautiful option. It's a project on GitHub, has Maven integration and loads of other options to keep it flexible.
集成指南：
更多信息：
这篇关于一个REST API的HOWTO文档自动化（泽西岛实施）的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！