如何自动化REST API的文档（Jersey实现） [英] Howto automate documentation of a REST API (Jersey Implementation)

问题描述

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

从环顾四周，大多数其他REST API也在手动创建他们的文档。但是我想知道这可能是一个很好的解决方案。

需要为每个端点记录的事情是：

• 服务名称


• 类别


• URI


• 参数


• 参数类型


• 响应类型


• 响应类型模式（XSD）


• 示例请求和回复


• 请求类型（Get / Put / Post / Delete）


• 描述


• 可能返回的错误代码

然而，当然还有一些一些全局的东西，例如

• 安全


• REST概述


• 错误处理


• 等等

这些一般事情都可以描述一次，不需要自动化，但是对于Web服务方法本身，似乎非常希望自动化它。

我已经想到可能使用注释，并编写一个生成XML的小程序，然后编写一个应用HTML生成实际文档的XSLT。使用自定义XDoclet更有意义吗？

任何帮助将不胜感激，
Alan

解决方案

Swagger 是一个很好的选择。它是GitHub的一个项目，具有Maven集成和其他选项的加载，以保持其灵活性。

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

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

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.

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:

• 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

• Security
• Overview of REST
• Error handling
• Etc

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.

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?

Any help would be much appreciated, Alan

解决方案

Swagger is a beautiful option. It's a project on GitHub, has Maven integration and loads of other options to keep it flexible.

Integration guide: https://github.com/swagger-api/swagger-core/wiki

More Information: http://swagger.io/

这篇关于如何自动化REST API的文档（Jersey实现）的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！