- html - 出于某种原因,IE8 对我的 Sass 文件中继承的 html5 CSS 不友好?
- JMeter 在响应断言中使用 span 标签的问题
- html - 在 :hover and :active? 上具有不同效果的 CSS 动画
- html - 相对于居中的 html 内容固定的 CSS 重复背景?
我的任务是为使用jaxrs开发的大型API寻找最佳方法,以供第三方记录。该代码目前在javadoc中有很好的文档说明。我的问题是帮助根据迄今为止的研究确定最佳方法,并验证我们走的是正确的道路,因此我正在寻找输入,评论或其他框架。我确信这是一个常见的用例,其他人也会遇到类似的问题,并非常感谢其他有经验的工作人员和文档编写人员的任何投入。
我们有以下要求:
我们没有大量的注释使代码混乱。
我们可以记录返回类型,例如嵌套对象及其正确的JSON结构。
我们可以指定标题,链接和元信息(意思是我们需要2.0而不是1.2)
我们希望尽可能地减少时间和成本,但仍保留高质量的文档。
与JDK 8。
我已经考虑了以下框架,但是每个框架似乎都有一些主要缺点,这些缺点要么使它们难以使用(对于本项目而言),要么使我产生误解。
Swagger JAXRS doclet:Link
这个maven插件在构建时就可以使用,并且能够基于现有的javadoc注释为我们提供合理的文档。 However, it does not support Swagger 2.0可能会限制在响应中描述标头,这对于我们的用例至关重要。它能够获取其余服务,而无需使用swagger maven插件所需的@Api或@ApiOperation批注。升级它以使用swagger 2.0可能是一项艰巨的任务。
Swagger Maven插件:Link
该插件在构建时根据注释而不是注释创建swagger文档。这将要求我们遍历整个项目并使用@Api和@ApiOperation进行注释。我们可能会摆脱仅在基类上的一些注释,但是对于端点的任何描述或标题,我们将需要在注释本身内添加详细信息。这些注解中的许多注解似乎都是重复的,例如,我们已经有@Get或@Post,但是仍然需要添加@ApiOperation并描述javadoc中已经描述的参数。失败的原因是这将花费时间,并且还会导致看起来很混乱的代码。
昂首阔步:Link
Swagger核心在运行时有效,这意味着我们无法从现有的Javadoc中删除注释。就像Swagger Maven插件一样,它很容易扩展,我们可以添加自己的阅读器或规则来添加链接和元信息(或使用我们自己的现有注释)。不利的一面是每种方法的描述都必须来自某个地方,因此必须在(还有更多)注释中添加这些注释,添加新代码时可能会忘记这些注释。
阐明:Link
由于我们需要能够在.NET上使用类似的框架,因此Enunciate不适用于我们,它也不支持JDK 8。
到目前为止我的结论
到目前为止,swagger jaxrs doclet最接近完成我们想要的一切。主要问题是缺乏敏捷2.0。我们需要能够相应地更新swagger版本,就像将一起记录在案的其他项目(不同的语言)一样。对我们来说第二好的是Swagger Maven插件,与自定义运行器一样,由于这是构建时间,因此应该可以以某种方式访问现有的javadoc注释并将其添加到生成的swagger中-我们可能可以避免使用一些注释位于基类上,并使用我们的自定义阅读器从注释中提取其余的注释(例如,描述)。最后,swagger核心并不能真正满足我们的需求,因为我们需要更多的注释来复制现有的javadoc。
由于更新swagger doclet以支持swagger 2.0所需的时间未知,我倾向于使用带有自定义阅读器的swagger maven插件(有关从中阅读javadoc注释的任何技巧都将非常有用!)。我是否错过了任何框架或细节,使我的结论不准确?
最佳答案
每个人都有自己的需求,因此我不会介绍建议的方式来处理您要执行的操作。但是您绝对可以通过创建自定义解析器来扩展swagger-maven-plugin项目,该解析器将通过SPI进行检测。
这不是一项微不足道的任务,但是如果您要这样做,那么就有支持它的基础结构。请在这里查看:https://github.com/swagger-api/swagger-parser#extensions
关于java - 使用Java的swagger自动生成其余端点,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/37397501/
我在网上搜索但没有找到任何合适的文章解释如何使用 javascript 使用 WCF 服务,尤其是 WebScriptEndpoint。 任何人都可以对此给出任何指导吗? 谢谢 最佳答案 这是一篇关于
我正在编写一个将运行 Linux 命令的 C 程序,例如: cat/etc/passwd | grep 列表 |剪切-c 1-5 我没有任何结果 *这里 parent 等待第一个 child (chi
所以我正在尝试处理文件上传,然后将该文件作为二进制文件存储到数据库中。在我存储它之后,我尝试在给定的 URL 上提供文件。我似乎找不到适合这里的方法。我需要使用数据库,因为我使用 Google 应用引
我正在尝试制作一个宏,将下面的公式添加到单元格中,然后将其拖到整个列中并在 H 列中复制相同的公式 我想在 F 和 H 列中输入公式的数据 Range("F1").formula = "=IF(ISE
问题类似于this one ,但我想使用 OperatorPrecedenceParser 解析带有函数应用程序的表达式在 FParsec . 这是我的 AST: type Expression =
我想通过使用 sequelize 和 node.js 将这个查询更改为代码取决于在哪里 select COUNT(gender) as genderCount from customers where
我正在使用GNU bash,版本5.0.3(1)-发行版(x86_64-pc-linux-gnu),我想知道为什么简单的赋值语句会出现语法错误: #/bin/bash var1=/tmp
这里,为什么我的代码在 IE 中不起作用。我的代码适用于所有浏览器。没有问题。但是当我在 IE 上运行我的项目时,它发现错误。 而且我的 jquery 类和 insertadjacentHTMl 也不
我正在尝试更改标签的innerHTML。我无权访问该表单,因此无法编辑 HTML。标签具有的唯一标识符是“for”属性。 这是输入和标签的结构:
我有一个页面,我可以在其中返回用户帖子,可以使用一些 jquery 代码对这些帖子进行即时评论,在发布新评论后,我在帖子下插入新评论以及删除 按钮。问题是 Delete 按钮在新插入的元素上不起作用,
我有一个大约有 20 列的“管道分隔”文件。我只想使用 sha1sum 散列第一列,它是一个数字,如帐号,并按原样返回其余列。 使用 awk 或 sed 执行此操作的最佳方法是什么? Accounti
我需要将以下内容插入到我的表中...我的用户表有五列 id、用户名、密码、名称、条目。 (我还没有提交任何东西到条目中,我稍后会使用 php 来做)但由于某种原因我不断收到这个错误:#1054 - U
所以我试图有一个输入字段,我可以在其中输入任何字符,但然后将输入的值小写,删除任何非字母数字字符,留下“。”而不是空格。 例如,如果我输入: 地球的 70% 是水,-!*#$^^ & 30% 土地 输
我正在尝试做一些我认为非常简单的事情,但出于某种原因我没有得到想要的结果?我是 javascript 的新手,但对 java 有经验,所以我相信我没有使用某种正确的规则。 这是一个获取输入值、检查选择
我想使用 angularjs 从 mysql 数据库加载数据。 这就是应用程序的工作原理;用户登录,他们的用户名存储在 cookie 中。该用户名显示在主页上 我想获取这个值并通过 angularjs
我正在使用 autoLayout,我想在 UITableViewCell 上放置一个 UIlabel,它应该始终位于单元格的右侧和右侧的中心。 这就是我想要实现的目标 所以在这里你可以看到我正在谈论的
我需要与 MySql 等效的 elasticsearch 查询。我的 sql 查询: SELECT DISTINCT t.product_id AS id FROM tbl_sup_price t
我正在实现代码以使用 JSON。 func setup() { if let flickrURL = NSURL(string: "https://api.flickr.com/
我尝试使用for循环声明变量,然后测试cols和rols是否相同。如果是,它将运行递归函数。但是,我在 javascript 中执行 do 时遇到问题。有人可以帮忙吗? 现在,在比较 col.1 和
我举了一个我正在处理的问题的简短示例。 HTML代码: 1 2 3 CSS 代码: .BB a:hover{ color: #000; } .BB > li:after {
我是一名优秀的程序员,十分优秀!