如何在 springdoc 中注释 requestBody 的各个元素？

Question

我有一个 spring（启动）服务器，想要使用 springdoc 从注释生成 OpenAPI 规范。

我有一个请求，请求正文中有两个参数。我希望第一个是必需的，第二个是可选的。

@RequestBody(required = {true|false})似乎只将主体中的所有参数设置为（不需要）。@Parameter另一方面，Javadoc说要使用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'

如何为所有四种请求类型只需要一个特定参数？

Answer 1

重要的

• 给定端点的请求正文不应超过 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.RequestBodySwagger 库中的 ，您仍然需要使用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 如下

数据传输组织

@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;
}