java - 如何自动化 REST API 的文档( Jersey 实现)-6ren

java - 如何自动化 REST API 的文档( Jersey 实现)

转载作者：IT老高更新时间：2023-10-28 13:53:38

25

4

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

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

每个端点需要记录的内容有:

服务名称
类别
URI
参数
参数类型
响应类型
响应类型架构 (XSD)
请求和响应示例
请求类型(Get/Put/Post/Delete)
说明
可能返回的错误代码

当然还有一些通用的东西是全局的，比如

安全
REST 概述
错误处理
等

这些一般的东西只需描述一次就可以了，不需要自动化，但是对于 Web 服务方法本身来说，自动化它似乎是非常可取的。

我考虑过可能使用注释，并编写一个生成 XML 的小程序，然后编写一个 XSLT，它应该在 HTML 中生成实际文档。使用自定义 XDoclet 是否更有意义？

最佳答案

Swagger是一个不错的选择。这是 GitHub 上的一个项目，具有 Maven 集成和许多其他选项以保持灵 active 。

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

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

enter image description here

关于java - 如何自动化 REST API 的文档( Jersey 实现)，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/1714029/

25

4

0

文章推荐： Java Primitives 范围计算

文章推荐： spring - 需要了解 spring.handlers 和 spring.schemas

文章推荐： spring - HQL查询两个日期之间的记录

rest - 非 RESTful 与 RESTful
我对编程真的很陌生，并且在理解 RESTful API 的概念时遇到了一些麻烦。我读过 REST 和 RESTful API。我已经查看了 SO 中已经提出的问题，但似乎无法更好地理解该主题。在我的
rest - 简单来说，REST，RESTFul，SOA和微服务是什么？
我以为我知道REST /“RESTFul”，restfulservices，webservices，SOA和微服务是什么，但是我遇到了许多不同的定义，我得出的结论是这些术语被过度使用，滥用或完全错误定
rest - SharePoint REST 在单个 REST 查询中获取用户标题
我有一个列表，其中有一个“人员和组”列。当我使用 REST 查询行时，我会在此列中列出用户 ID。我发现这篇文章将帮助我将每个 id 转换为标题 http://www.codeproject.com
rest - 什么是 REST 调用以及如何发送 REST 调用？
我想问一些关于 REST 调用的问题。我是 REST 调用的绿色，我想了解什么是 REST 调用以及如何使用 URL 向服务器发送 REST 调用。谁能给我一些基本的教程或链接供我引用？另外，如果我
rest - 为什么 REST Web 服务称为 REST
很难说出这里问的是什么。这个问题模棱两可、含糊不清、不完整、过于宽泛或言辞激烈，无法以目前的形式合理回答。如需帮助澄清此问题以便可以重新打开，visit the help center . 8年前关闭
rest - 什么是监视 REST 资源以进行更改的 RESTful 方式？
如果有一个 REST 资源我想监视来自其他客户端的更改或修改，那么最好(也是最 RESTful)的方法是什么？我这样做的一个想法是通过提供特定资源来保持连接打开，而不是在资源不(尚)存在时立即返回。
rest - RESTful 服务中的分页
我有一个可以返回大量项目的 RESTful API，我希望能够使用分页样式技术来限制项目数量，这是 RESTful API 中的一个好主意吗？如果有可能最好通过链接(在这种情况下为 url)或请求正
rest - RESTful 发布多个实体的策略
我仍然处于适应以 REST 方式做事的过程中。在我的情况下，客户端软件将与 RESTful 服务交互。很少，客户端会上传其整个实体数据库(每个实体序列化为大约 5kb 的 xml 块)。也许我错了
rest - REST 中的子资源和路径变量冲突？
设计一个路径解析可能有歧义的 REST API 是否被认为是不好的做法？例如: GET /animals/{id} // Returns the animal with the given ID
rest - REST 是如何无状态的？
我知道 REST 并且知道在不使用 session 的情况下创建 RESTful Web 服务，我更了解它，但我不太了解无状态的概念以及使用 REST 如何使您的应用程序可扩展有人可以解释 REST
rest - REST API的单点登录支持
我正在尝试找到解决以下问题的最佳方法:我们的应用程序是SaaS，它支持Web登录的SAML。该应用程序还公开了应该在自动化和无人值守的流程中使用的REST API，这意味着没有交互式用户可以键入凭据。
rest - REST 是否可以建立连接池？
由于 REST 是无状态的，因此传入的每个请求都不知道传入的前一个请求。在这种情况下是否可以使用连接池？如果要实现连接池，它将像标准数据库连接一样在每个请求时打开连接池并关闭它。如何实现 REST
rest - 得墨忒耳定律与 REST
得墨忒耳定律(真的应该是得墨忒耳的建议)说你不应该“穿过”一个物体去接触它们的子物体。如果您作为客户需要执行一些重要的操作，大多数情况下您使用的域模型应该支持该操作。 REST 原则上是一个愚蠢的对象
rest - 通过示例了解 REST
我唯一真正接触到 REST 的想法已经通过 Ruby on Rails 的 RESTful routing .这非常适合我使用 Rails 构建的基于 CRUD 的应用程序，但因此我对 RESTful
rest - RESTful URL的好处
有什么好处 http://www.example.com/app/servlet/cat1/cat2/item 网址超过 http://www.example.com/app/servlet?c
rest - REST 服务中的建模操作
我知道以前有人问过这类问题。我有我的问题的解决方案，我想知道我是否在任何地方破坏了 REST 或 HTTP 主体。在我的系统中，我有一个名为 member 的资源。支持通常的GET/POST/PUT
rest - REST API响应部分成功
我有一个API，可以执行一些批量处理任务。假设它确实为某些资源命名。我批量传递了7个请求，其中5个更新成功，2个失败。我的问题是如何应对。使用HTTP时，我无法同时返回成功和错误。有一个部分成功
rest - RESTful 单例资源
我来自 RPC 世界，但目前正在调查使用 REST 是否适合我的项目。至于据我了解 Wikipedia RESTful 服务的基本思想是提供对集合及其各个元素的访问。在我的情况下，服务器将是一个测量
rest - Tapestry + REST
我想将REST添加到我的挂毯项目中，因此需要知道如何实现它。有什么更好的方法？谢谢。 [编辑，从答案中复制:]我必须将GET，PUT，POST和DELETE服务添加到我的挂毯应用程序中。我看到Ta
rest - RESTful 服务中的资源级别授权
让 /users/{id}成为 RESTful 服务中的资源 url。启用基本身份验证，只有经过身份验证的用户才能访问该 url。示例场景: User_1 & User_2是经过身份验证的用户，用

首页

博学

6Ren·AI

商城

java - 如何自动化 REST API 的文档( Jersey 实现)