Question

我有一个带有两个端点的控制器类

@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或网络浏览器访问端点

http://localhost:8081/test

返回

无参数测试

和

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

返回

使用参数进行测试

但是swagger ui只显示了一个没有参数的

如果我将请求的请求映射中的值更改为

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

Swagger UI可以正确显示两个端点，但是我宁愿不根据将显示或不显示什么摇头来定义端点。

我有什么办法让swagger ui正确显示具有匹配值但参数不同的端点？

编辑说明：

端点工作正常； / test和/ test？param = 1都可以正常工作，问题在于swagger-ui不会显示它们。

我想让swagger ui显示我定义的端点，但是如果不能显示，那么我将不得不忍受swagger-ui缺少某些端点的情况。

参考引用进行编辑：

在这里回答的人：Proper REST formatted URL with date ranges

明确地说不要用斜杠分隔查询字符串

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

Answer 1

我不清楚您要尝试执行的操作，但是我将提供两种解决方案：

如果您要使用PATH参数，例如GET /test和GET /test/123您可以做到：

  @GetMapping("/test")
  public String getTest() {
    return "test without params";
  }

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

如果要查询参数（GET /test和GET /test?param=123），则需要一个带有可选参数的端点：

  @GetMapping("test")
  public String getTest(@RequestParam("param") Integer param) {
    if(param == null) { 
      return "test without params";
    } else {
      return "test with param";
    }
  }

Answer 2

尝试在以下路径中包含参数。

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

Answer 3

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

尝试将第二种方法更改为以下方法。由于要在QueryParam中提供输入而不是路径变量，因此应使用@RequestParam而不是@PathParam。

请注意，您必须给/ test /，以便告诉Spring您的映射不是模棱两可的。希望对您有所帮助。

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

Answer 4

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

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

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

您将其实现为两个单独的控制器端点这一事实是一个实现细节，并不会改变可以操作单个 /test 资源的事实。

通过在 swagger UI 中将其列为两个单独的端点与具有可选参数的单个端点相比，您的 API 的使用者有什么好处？也许它可以限制允许的有效查询参数集（如果您设置 ?foo，则必须设置 &bar），但这也可以在描述性文本中完成，并且是一种更标准的方法。就我个人而言，我不熟悉任何公开记录的 api，这些 api 通过查询参数区分同一资源的多个操作。

如何使Swagger UI显示类似的Spring Boot REST端点？

4 个答案: