问题描述
我使用 Java Jersey(和 JAXB)编写了一个非常广泛的 REST API.我也使用 Wiki 编写文档，但它是一个完全手动的过程，非常容易出错，尤其是当我们需要进行修改时，人们往往会忘记更新 Wiki.
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 也在手动创建他们的文档.但我想知道是否有一个好的解决方案.
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)
- 示例请求和响应
- 请求类型(获取/放置/发布/删除)
- 说明
- 可能返回的错误代码
当然还有一些通用的东西是全局的，比如
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 的小程序，然后编写一个 XSLT 生成实际的 HTML 文档.使用自定义 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?
推荐答案
Swagger 是一个不错的选择.它是 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.
集成指南:https://github.com/swagger-api/swagger-core/wiki
更多信息:http://swagger.io/
这篇关于如何自动化 REST API 的文档(泽西岛实现)的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！