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

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 或 Web 浏览器来访问端点

http://localhost:8081/test

返回

无参数测试

和

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

返回

用参数测试

但是swagger ui只显示没有参数的那个。

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

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

Swagger UI 正确显示两个端点，但我不希望根据 swagger 将显示或不显示什么来定义我的端点。

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

编辑澄清：

端点工作得很好； /test 和 /test?param=1 都可以正常工作，问题是 swagger-ui 不会显示它们。

我希望 swagger ui 显示我定义的端点，但如果不能，那么我将不得不忍受 swagger-ui 缺少我的一些端点。

参考编辑：

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

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

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

Answer 1

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

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

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

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

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

Answer 2

我不清楚你到底想做什么，但我会给出两个解决方案：

如果你想有 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 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

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

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