Grails REST XML API 定义

Question

为了发布一个有据可查的应用程序，我正在寻找一种为我的 Grails 应用程序用户描述 REST API 的好方法。

我知道 REST 调用应该足够简单，可以通过示例来描述，但感觉不够正式。

我花了几个小时寻找其他 Grails 用户建议的解决方案，但除了使用 WADL 或 WSDL 2.0 的建议之外没有找到一个简洁的解决方案

This 看起来是个不错的方向，但在 Grails 中必须有一个简单的方法。

我希望能提供一些指导，以根据我的模型对象生成 REST API，最好能够过滤或控制暴露的字段，另外，还有一种很好的图形方式来呈现它（类似于 XSD Eclipse 插件)

谢谢！ 伙计

Answer 1

我建议在 API 文档中避免使用 WADL 或 WSDL，您可以在我解释原因的地方看到这个问题：Why the slow WADL uptake。

WADL 或 WSDL 通常用于自动生成客户端代码，它们不是人类可读的文档。我不认为 WADL 或 WSDL 对用户弄清楚如何正确使用资源非常有用。

我更喜欢良好的旧 html 文档，例如我喜欢 twitter 记录他们的 API 的方式

如果您坚持自动生成资源文档，我可以在 ATOM service document 上推荐。许多 REST 框架可以根据资源注释自动生成它。 （例如 Apache Wink）