如何使用 Spring 自我描述 REST API?

Question

我正在使用spring-mvc来创建如下servlet：

@RestController
public class MyServlet {
@GetMapping("/test")
public MyRsp test(MyReq req) {
//...
}
}

现在，如果用户访问我的应用程序localhost:8080/my-app的根目录，它应该显示可用的GET和POST方法的列表。充其量是可能的输入参数、可接受的标头等。

问题：任何弹簧框架(如HATEOAS)都可以这样做吗？

我希望一个框架可以自动检测任何@RestController和包含的方法。

还是我必须自己创建该概述页面？

Answer 1

你应该研究一下

要在春季集成它，您可以参考这个

Swagger是公开RESTful API的最佳框架之一。

Answer 2

Swagger 2是另一种选择。 阅读以下内容以了解有关 Swagger 以及如何设置它的更多信息。

使用 Spring REST API 设置 Swagger 2

您还可以为 rest API 创建 swagger 定义，客户端可以使用该定义来生成客户端类。

此外，swagger用户界面可用于测试/调用您的API。 Swagger提供了一个用户界面，您可以在其中输入所有API输入，例如查询参数，路径参数，请求正文，标头。

招摇用户界面示例

Answer 3

你可以查看这个项目Spring Restdocs(github)，它允许你生成现成的REST文档。它由Spring Team正式维护：

该项目的主要目标是使其易于记录 通过组合手写的内容来提供 RESTful 服务 带有使用Spring MVC自动生成的示例的Asciidoctor。 测试框架。结果旨在成为易于阅读的用户 指南，例如类似于GitHub的API文档，而不是 由以下工具生成的全自动、密集的 API 文档 斯瓦格。

另一种选择是使用Swagger，它也支持自下而上的方法：

一种自下而上的方法，其中您有一个现有的 REST API，您可以为其提供 想要创建一个招摇定义。要么创建定义 手动(使用上面提到的相同的 Swagger 编辑器)，或者如果您 正在使用受支持的框架之一(JAX-RS、node.js 等)，您 可以获取为您自动生成的 Swagger 定义。

这里提到了一些招摇的例子：1 2