spring 如何让Swagger UI显示类似的Sping Boot REST端点?

yzuktlbb  于 2023-02-03  发布在  Spring
关注(0)|答案(5)|浏览(166)

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

@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
退货
带参数测试
但是SwaggerUI只显示没有参数的那个。
如果我将请求Map中的值更改为参数

@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
明确说明不要用斜杠分隔查询字符串
他们还说“查询字符串前不应该有斜杠”。

6ie5vjzr

6ie5vjzr1#

问题出在请求Map中,第二个方法声明覆盖了第一个方法。因为资源Map值相同。
尝试将第二个方法更改为下面的方法。由于您希望在QueryParam而不是路径变量中给予输入,因此应使用@RequestParam而不是@PathParam。
注意,你必须给予/test/,以便告诉Spring你的Map不是二义性的。希望它能有所帮助。

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

rt4zxlrg2#

在阅读澄清,这里的问题是,swagger-ui是做正确的事情。
您有两个控制器端点,但它们是针对同一个RESOURCE /test的,该RESOURCE /test接受一组可选的查询参数。
实际上,具有相同方法(GET)和请求Map(/test)的所有Map的控制器端点表示单个 * 逻辑 * 资源、test资源上的GET操作以及可能影响调用该操作的结果的一组可选参数。
您已经将其实现为两个独立的控制器端点,这是一个实现细节,并不会改变可以操作单个/test资源的事实。
在swaggerUI中将其列为两个单独的端点与将其列为具有可选参数的单个端点相比,对API的使用者有什么好处?也许它可以约束允许的有效查询参数集(如果你设置?foo你必须设置&bar)但是这也可以在描述性文本中完成,并且是一种标准得多的方法。我不熟悉任何公开文档化的API,这些api通过查询参数来区分同一资源的多个操作。

mklgxw1f

mklgxw1f3#

根据开放API规范3
OpenAPI将唯一操作定义为路径和HTTP方法的组合。这意味着不允许对同一路径使用两个GET或POST方法--即使它们具有不同的参数(参数对唯一性没有影响)。
参考-https://swagger.io/docs/specification/paths-and-operations/
这也是一个问题,但已关闭,因为OAS3不允许-https://github.com/springdoc/springdoc-openapi/issues/859

3xiyfsfu

3xiyfsfu4#

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

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

wvt8vs2t5#

我不清楚你到底想干什么,但我会给予两个解决方案:
如果您想使用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 /testGET /test?param=123),则需要一个带有可选参数的端点:

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

相关问题