如何自动执行 REST API 的文档（泽西岛实现）[已关闭]

rest java documentation automation jersey

2022-08-31 15:41:05

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

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

需要为每个端点记录的内容是：

当然，还有一些全球性的一般事物，例如

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

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

答案 1

炫耀是一个美丽的选择。这是GitHub上的一个项目，具有Maven集成和许多其他选项，以保持其灵活性。

enter image description here

答案 2

不幸的是，Darrel的答案在技术上是正确的，但在现实世界中却是hocus-pocus。它基于只有一些人同意的理想，即使你对此非常小心，也有可能由于某种超出你控制范围的原因，你不能完全遵守。

即使你可以，其他可能不得不使用你的API的开发人员可能并不关心或知道RESTful模式的细节......请记住，创建API的目的是使其他人能够轻松使用它，并且必须提供良好的文档。

然而，Achim关于WADL的观点很好。因为它存在，我们应该能够创建一个基本的工具来生成API的文档。

有些人已经走了这条路，并且已经开发了一个XSL样式表来进行转换：https://wadl.dev.java.net/