Java 和 OpenAPI - 根据响应代码返回不同的负载

Question

在开始之前:我查看了以下链接，但没有一个链接符合我的问题:

• Swagger - Specify Optional Object Property or Multiple Responses
• Swagger; specify two responses with same code based on optional parameter
• Swagger - Specify Optional Object Property or Multiple Responses

因此，我有一个端点的 OpenAPI 3 定义，该端点返回成功调用的给定负载(例如 200 OK)。但是，对于不成功的调用(例如 408 CONFLICT)，我想返回完全不同的错误负载。

您可以看到下面的定义:

openapi: 3.0.1

info:
  title: Dogs
  description: API to add dogs into a database
  version: 0.0.1

paths:
  /dog:
    post:
      description: Saves a dog into the database

      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Dog"

      responses:
        201:
          description: A dog was added to the system
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Dog"

        400:
          description: This dog already exist in the system
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    Dog:
      type: object
      properties:
        name:
          type: string
          description: Name of the dog
          example: "barky"

    Error:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable code of the error.
          example: "Already Exists"

        message:
          type: string
          description: A Human-readable error message.
          example: "Empty string is not a valid name for a dog"

由此，我生成 Spring 代码(当前使用 Swagger 编辑器)。与定义关联的方法签名如下所示:

ResponseEntity<Dog> dogPost(@ApiParam(value = ""  )  @Valid @RequestBody Dog body);

因此 - 我无法在此函数中返回 Error 对象，除非抛出异常并稍后捕获 - 我认为这是一种不好的做法，因为无效输入的操作不是异常。

有没有办法很好地解决这个问题，而不抛出异常并在函数作用域之外捕获它？

Answer 1

使用 Spring Boot 有很多方法可以实现这种需求。其中之一是使用 @ExceptionHandler (有关更多信息，请参阅 https://www.baeldung.com/exception-handling-for-rest-with-spring)，但这确实是在 Controller 本身之外处理的。该系统的优点是您可以在 1 个位置实现任何 Exception 到错误对象的转换，而不是单独每个 Controller 方法。

也就是说，如果您确实想在 Controller 本身中处理它，您可以这样做:

@PostRequest("/dog")
public ResponseEntity<?> createDog(@Valid @RequestBody Dog dog) {
    if( !service.doesDogAlreadyExist(dog) ) {
      Dog dog = service.createDog(dog);
      return ResponseEntity.ok(dog).build();
    } else {
      return ResponseEntity.status(HttpStatus.CONFLICT)
                           .body(/* error object here */)
    }
}