如何注释以在 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 个！
Request Body 主要是一个 JSON 对象。因此，为了使主体中的某些属性成为强制性的，建议使用验证 api.
有 2 个 @RequestBody 注释。一个来自 Spring 框架 org.springframework.web.bind.annotation.RequestBody，另一个来自 io.swagger.v3.oas.annotations.parameters.RequestBody

重要的是，即使您使用 Swagger 库中的 io.swagger.v3.oas.annotations.parameters.RequestBody，您仍然需要使用 org.springframework.web.bind.annotation.RequestBody 来接收实际对象。

如下重构代码应该对您的情况有所帮助

控制器Class

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

Answer 2

不建议将请求体添加到 GET 请求中，即使您可以...查看 here。

控制器class方法：

@GetMapping("/fstVector")
public ResponseEntity<Vector> fstV(
        @RequestParam final Vector v1,
        @RequestParam(required = false) final Vector v2) {
    return new ResponseEntity<>(v1, HttpStatus.OK);
}

@PostMapping("/fstVector")
public ResponseEntity<Vector> fstVPost(
        @Valid
        @org.springframework.web.bind.annotation.RequestBody
        @io.swagger.v3.oas.annotations.parameters.RequestBody
        final VectorRequest vectorRequest) {
    return new ResponseEntity<>(vectorRequest.getV1(), HttpStatus.OK);
}

DTO 对象：

public class VectorRequest {
    @NotNull
    Vector v1;
    Vector v2;

    public Vector getV1() {
        return v1;
    }

    public void setV1(Vector v1) {
        this.v1 = v1;
    }

    public Vector getV2() {
        return v2;
    }

    public void setV2(Vector v2) {
        this.v2 = v2;
    }
}

参数 v1 是必需的，v2 是可选的。

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

How to annotate to require individual elements of requestBody in springdoc?

spring-boot

openapi

springdoc

springdoc-openapi-ui