如何自动化REST API文档(Jersey实现)
Ala*_*nan 62 java documentation rest automation jersey
我使用Java Jersey(和JAXB)编写了一个非常广泛的REST API.我还使用Wiki编写了文档,但它是一个完全手动的过程,非常容易出错,特别是当我们需要进行修改时,人们往往忘记更新wiki.
从四处查看,大多数其他REST API也可以手动创建文档.但我想知道这是否可能是一个很好的解决方案.
需要为每个端点记录的事物类型是:
- 服务名称
- 类别
- URI
- 参数
- 参数类型
- 响应类型
- 响应类型架构(XSD)
- 样本请求和响应
- 请求类型(获取/放置/发布/删除)
- 描述
- 可能返回的错误代码
然后当然有一些全球性的事情,如
- 安全
- REST概述
- 错误处理
- 等等
这些一般的东西可以描述一次并且不需要自动化,但对于Web服务方法本身来说,似乎非常希望自动化它.
我想过可能会使用注释,编写一个生成XML的小程序,然后是一个XSLT,它应该用HTML生成实际的文档.使用自定义XDoclet更有意义吗？
Web*_*net 41
Swagger是一个很好的选择.它是GitHub上的一个项目,具有Maven集成和其他选项以保持其灵活性.
集成指南:https://github.com/swagger-api/swagger-core/wiki
更多信息:http://swagger.io/
- 更多信息在这里:http://swagger.wordnik.com和集成文档在这里:https://github.com/wordnik/swagger-core/wiki (2认同)
Bri*_*pin 21
不幸的是,达雷尔的答案在技术上是正确的,但却是现实世界的焦点.这是基于理想的,只有一些人同意,即使你非常小心,很可能由于某种原因,你无法控制,你不能完全符合.
即使你可以,其他可能不得不使用你的API的开发人员也可能不关心或不了解RESTful模式的细节......请记住,创建API的目的是让其他人能够轻松使用它,并且良好的文档是必须.
Achim关于WADL的观点很好.因为它存在,我们应该能够创建一个生成API文档的基本工具.
有些人采用了这种方法,并开发了一个XSL样式表来进行转换:https: //wadl.dev.java.net/
- Chrome由操作员控制.大多数API客户端都是自动的 如果您想使用机器人导航`Stackoverflow.com`,您需要了解有关网站结构和预期用途的深入了解.您不会"从根URL中探索它",也不希望媒体类型"text/html"提供很多帮助.您最终会手动探索它,以创建一个好的API文档提供的那种地图. (8认同)
- stackoverflow API有很好的文档(参见https://api.stackexchange.com/docs),这种不记录ReSTful API的概念在现实世界中是荒谬的,并且不以任何方式帮助回答原始问题. (4认同)
- 没必要打斗达雷尔.我不知道堆栈溢出人员在API方面设置了什么,我不太关心,因为我不需要它.如果他们没有为他们的API提供文档,那么我为那些必须整合的人感到遗憾. (2认同)
- 没有任何侵略意图.我也不是指Stackoverflow API.我指的是网站.该网站通过HTTP工作,并被称为"Web浏览器"的客户端应用程序使用.我的观点是,当您构建网站时,您无需致电Google告诉他们如何调整Chrome以便它可以使用您的网站.通过使用记录良好的媒体类型,不需要"API"文档. (2认同)
小智 8
您可能对Jersey能够在运行时以XML格式为所有已发布资源提供所谓的WADL描述(从注释自动生成)感兴趣.这应该已经包含了基本文档所需的内容.此外,您可以添加其他JavaDoc,但这需要更多配置.
请看这里:https: //jersey.java.net/documentation/latest/wadl.html
Dar*_*ler -2
我讨厌传递坏消息，但如果您觉得需要记录您列出的内容，那么您可能没有创建 REST 接口。
REST 接口通过识别单个根 URL，然后描述从该 URL 返回的表示的媒体类型以及可以通过该表示中的链接访问的所有媒体类型来记录。
您使用什么媒体类型？
另外，请在您的文档中添加RFC2616的链接。这应该向任何消费者解释如何与您的服务进行交互。
- 这很愚蠢。REST API 就是一个 API。没有办法编写一个知道如何与每个 REST API 交互的通用客户端，无论它们的自我文档化程度如何。客户会对内置的 API 有一定的了解，并且生成文档来描述该 API 似乎很合理。 (16认同)
- @DarrelMiller 根据 Roy Fielding (http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven) 的说法，RESTful 系统必须是超文本驱动的，这是正确的。然而，我认为这是一个极端的立场，有大量且富有成效的 API 类拥抱 HTTP 并强调名词、媒体类型、无状态性、文档版本控制等，但废除了 HATEOAS 并允许客户端构建自己的 URL ...这就是当今大多数人通俗地称为“休息”的地方。如果我们有一个新术语那就太好了。 (6认同)
- @Ted 你能给我看看网络浏览器开发人员在为 StackOverflow 网站构建支持时使用的文档吗？在你回来之前“但是网络浏览器是不同的”。问问自己，为什么它们不同。它们是本机应用程序，使用来自公开资源的 HTTP 服务器的 HTML/CSS/jpeg/png 媒体类型。 (4认同)
- @Darrel Chrome *可以工作*，因为有标准，而且它只是渲染。除非被告知，否则它不会与服务交互，即使如此，用户也必须向其提供准确的指令和 Chrome 的 URI 来执行交互。这不是魔法。大多数 REST 客户端都有基于响应数据结构的自定义交互和客户呈现方案。我不知道没有文档你是如何度过的，除非你是唯一的消费者。不要谈论浏览器和网络，而是向我展示现实世界的 REST 服务，这些服务具有零文档，很容易为其编写客户端。 (4认同)
- 好吧，您可能仍然想为您拥有的不同路线提供文档，对吧？ (3认同)
- 如果您指的是 Discovery 将是 REST 接口的足够文档，那么您要么不擅长编写 API，要么正在编写非常小且易于理解的服务。我想说的是，很难为 API 自动生成良好的文档，因为您需要考虑用户目标和工作流程。大多数情况下，我们会考虑“我的 API 可以做什么，我的特定资源可以做什么”，而不是“用户想要做什么？”……REST 通过允许您告诉我们，从而利用了这一点“你可以从这里做什么”，但这可能还不够。 (3认同)
- @Nate我讨厌这些答案。文档不仅仅适用于开发人员。我无法将 HTTP 上的 RFC 规范交给我的销售人员，并要求他们的潜在客户自行解决。啊，您已经从事软件工作 20 多年了 - 现在一切都有意义了...... (3认同)
- @DarrelMiller 正在谈论 HATEOAS：RESTful 文档应该包含枚举所有可能的“后续步骤”或“相关项目”的链接。这对于 HTML 来说是有意义的，因为我们希望浏览器在页面上显示链接，这样我们只需单击即可导航，而不是不断在 URL 框中键入新的 URL。但对于 RESTful API 来说，这没有多大意义：自动化客户端需要了解其正在对话的服务的一些信息，并且要求客户端编写其所需的 URL 并非不合理。 (3认同)
- 这是一个毫无成效、白日梦的答案，比 Stack Overflow 更适合哲学讨论。请注意，这种讨论会很有趣，但这里只是劝说。 (3认同)
- @MichaelIles 我们中的许多人简称为 HTTP API。不幸的是，没有更多公开可见的超媒体驱动的 API。我认为您不需要很长时间就能发现它们并不像人们所认为的那样“极端”，而且在实际场景中实际上非常有效。 (2认同)
- 这个答案完全是无稽之谈，它使用了 REST 服务的迂腐定义，并且完全脱离了现实世界中如何使用 REST 的现实。 (2认同)
| 归档时间： |
|
| 查看次数： |
51318 次 |
| 最近记录： |