如何让Swagger UI显示类似的Spring Boot RESTendpoint？

Question

我有一个具有两个endpoint的控制器类

@RestController
@RequestMapping
public class TestController {

  @RequestMapping(
          value= "/test",
          method = RequestMethod.GET)
  @ResponseBody
  public String getTest() {
    return "test without params";
  }

  @RequestMapping(
          value= "/test",
          params = {"param"},
          method = RequestMethod.GET)
  @ResponseBody
  public String getTest(@PathParam("param") int param) {
    return "test with param";
  }

}

一个有一个参数，一个没有，两者都起作用。

如果我使用curl或web浏览器访问endpoint

http://localhost:8081/test

返回

无参数测试

和

http://localhost:8081/test?param=1

返回

参数测试

但是，swagger ui只显示没有参数的用户界面。

如果我使用参数将请求的请求映射中的值更改为

  @RequestMapping(
          value= "/testbyparam",
          params = {"param"},
          method = RequestMethod.GET)

Swagger UI可以正确显示两个endpoint，但是我不想根据swagger将显示或不显示的内容来定义我的endpoint。

我有没有办法让swagger ui正确显示具有匹配值但参数不同的endpoint？

编辑澄清：

endpoint工作得非常好/测试和/或测试？param=1两者都能完美工作，问题是swagger ui不会显示它们。

我想让swagger ui显示我定义的endpoint，但是如果它不能，那么我只能忍受swagger ui缺少我的一些endpoint。

参照编辑：

回答这里的人：正确的REST格式的URL和日期范围

明确表示不要用斜杠分隔查询字符串

他们还说“查询字符串前不应该有斜杠”

Answer 1

尝试在路径中包含参数，如下所示。

@GetMapping("/test/{param}")
public String getTest(@PathVariable final int param) {
    return "test with param";
}

Answer 2

在阅读澄清后，这里的问题是swagger-ui正在做正确的事情。

您有两个控制器endpoint，但它们用于相同的RESOURCE/test，该endpoint采用一组可选的查询参数。

实际上，具有相同方法（GET）和请求映射（/test）的所有映射控制器endpoint都表示一个逻辑资源。获取test资源上的操作，以及一组可能影响调用该操作结果的可选参数。

将其实现为两个独立的控制器终结点的事实是一个实现细节，并且不会改变可以对单个/test资源进行操作的事实。

在swagger UI中将其列为两个独立的endpoint，而不是带有可选参数的单个endpoint，这对API的使用者有什么好处？也许它可以约束允许的有效查询参数集（如果设置？foo，则必须设置

Answer 3

问题在于您的请求映射中，第二个方法声明将覆盖第一个方法。因为资源映射值是相同的。

尝试将第二种方法更改为下面。因为你想在QueryParam而不是path变量中输入，所以你应该使用@recestParam而不是@PathParam。

请注意，您必须给出/test/，以便告诉Spring您的映射没有歧义。希望能有帮助。

@RequestMapping(
          value= "/test/",
          method = RequestMethod.GET)
  @ResponseBody
  public String getTest (@RequestParam("param") int param) {
    return "test with param"+param;
  }