rest - 我使用 clojure 创建 REST API。如何自动生成REST文档？

Question

我正在编写 clojure rest 服务(使用 ring、compojure 和 liberator)，并希望为我所有的 REST API 自动生成 API 文档。手动生成非常繁琐。有什么方法可以使用注释或类似的东西吗？如果我能用 lein gen-rest-docs 做到这一点，那就太棒了。

Answer 1

REST 架构风格的“Uniform Interfaces" 属性不鼓励为单个端点编写文档。在 REST 中，您依靠自描述消息和超链接来驱动应用程序。

虽然我知道您需要记录您的 API，但我建议您重点记录媒体类型如何应用于您的领域以及实现中的一般假设。这通常包括授权、SLA。如果您正确使用媒体类型和超链接，那么单个资源就不再需要太多文档。

如果这对您来说没有选择，那么请注意您拥有 RPC 架构。在这种情况下 ring-swagger和类似的解决方案可以提供帮助。