我有一个 spring(启动)服务器,想要使用 springdoc 从注释生成 OpenAPI 规范。
我有一个请求,请求正文中有两个参数。我希望第一个是必需的,第二个是可选的。
@RequestBody(required = {true|false})
似乎只将主体中的所有参数设置为(不需要)。
Javadoc 的@Parameter
另一方面说使用io.swagger.v3.oas.annotations.parameters.RequestBody
这是我的代码,我希望生成一个规范,其中第一个参数是必需的,第二个参数是可选的:
@GetMapping("/fstVector")
public ResponseEntity<Vector> fstV(@RequestBody final Vector v1, @RequestBody(required = false) final Vector v2) {
return new ResponseEntity<>(v1, HttpStatus.OK);
}
@PostMapping("/fstVector")
public ResponseEntity<Vector> fstVPost(@RequestBody(required = true) final Vector v1, @RequestBody(required = false) final Vector v2) {
return new ResponseEntity<>(v1, HttpStatus.OK);
}
然而,生成的规范需要两个参数:
/pond/fstVector:
get:
tags:
- circle-escape-controller
operationId: fstV
parameters:
- name: v1
in: query
required: true
schema:
$ref: '#/components/schemas/Vector'
- name: v2
in: query
required: true
schema:
$ref: '#/components/schemas/Vector'
responses:
"200":
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/Vector'
post:
tags:
- circle-escape-controller
operationId: fstVPost
requestBody:
content:
application/json:
schema:
type: object
properties:
v1:
$ref: '#/components/schemas/Vector'
v2:
$ref: '#/components/schemas/Vector'
required: true
responses:
"200":
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/Vector'
如何为所有四种请求类型只需要一个特定参数?
重要的
- 给定端点的请求正文不应超过 1 个!
- 请求正文主要是一个 JSON 对象。因此,为了使正文中的某些属性成为必需,建议使用验证 api。
- 有2个
@RequestBody
注释。一种来自 Spring 框架org.springframework.web.bind.annotation.RequestBody
另一个来自io.swagger.v3.oas.annotations.parameters.RequestBody
重要的是,即使您使用io.swagger.v3.oas.annotations.parameters.RequestBody
从 Swagger 库中,您仍然需要使用org.springframework.web.bind.annotation.RequestBody
接收实际对象。
重构如下代码应该对您的情况有帮助
控制器类
@GetMapping("/fstVector")
public ResponseEntity<Vector> fstV(
// we generally use @RequestParam for query parameters. Query parameters are generally optional and thus the "required" attribute of @Parameter defaults to "false"
@Parameter @RequestParam final Vector v1,
// set @Parameter to TRUE if the parameter must be passed.
@Parameter(required = true) @RequestParam final Vector v2
) {
return new ResponseEntity<>(v1, HttpStatus.OK);
}
@PostMapping("/fstVector")
public ResponseEntity<Vector> fstVPost(
// RequestBody objects are "required" by default. To make them optional, add "(required = false)"
@org.springframework.web.bind.annotation.RequestBody // Spring
@io.swagger.v3.oas.annotations.parameters.RequestBody // Swagger
@Valid // Bean validation to ensure if the incoming object is valid
final Vector v1
) {
return new ResponseEntity<>(v1, HttpStatus.OK);
}
对于域对象,重构 DTO 如下
DTO
@Schema(description = "My DTO")
class Vector {
// The below attribute is required
@NotNull
@Parameter(description = "my first attribute", required = true)
String attribute1;
// The below attribute is optional
@Parameter(description = "my second attribute", required = false)
String attribute2;
}
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系:hwhale#tublm.com(使用前将#替换为@)