如何自动化REST API文档（Jersey实现） [英] How to automate documentation of a REST API (Jersey Implementation)
问题描述
我使用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）
- 示例请求和回复
- 请求类型（获取/放置/发布/删除）
- 描述
- 可能返回的错误代码
- Service Name
- Category
- URI
- Parameter
- Parameter Types
- Response Types
- Response Type Schema (XSD)
- Sample requests and responses
- Request type (Get/Put/Post/Delete)
- Description
- Error codes which may be returned
然后当然有一些全局性的东西，如
And then of course there are some general things which are global such as
- 安全性
- REST概述
- 错误处理
- Etc
- Security
- Overview of REST
- Error handling
- Etc
这些一般事情可以描述一次，不需要自动化，但对于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文档（Jersey实现）的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
