带有org.springdoc的Swagger-UI (v3)无法正确显示和解释枚举

Question

我的Swagger-UI有一个问题:它确实显示了预期的枚举。

它不是像CATEGORY1这样的简单表示，它显示了像CATEGORY1(name=Cat 1)这样的完整类，并且还在像http://localhost:8080/file/byCategory?category=Category.CATEGORY1%28name%3DCat%201%29这样的请求中使用它

我认为我可以使用正确的Enum-descriptions发送请求(例如，使用Postman)，服务器将响应，因此api本身可以工作。

对此问题很重要的依赖项：

 <dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
 </dependency>

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-data-rest</artifactId>
    <version>1.5.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-webmvc-core</artifactId>
    <version>1.5.0</version>
</dependency>

我还使用了Spring Boot (2.4.0)和其他一些依赖项，这不应该是问题的一部分。

我的控制器：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.util.ObjectUtils;
import org.springframework.web.bind.annotation.CrossOrigin;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;

import javax.servlet.http.HttpServletResponse;
import java.util.List;

@Slf4j
@RestController
@RequestMapping("/file")
@CrossOrigin(origins = "http://localhost:4200")
@Tag(name = "Files")
public class GridFSController {

private final GridFsService service;

@Autowired
public GridFSController(GridFsService service) {
    this.service = service;
}

@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
@Operation(summary =  "Upload a document")
@ResponseBody
public ResponseEntity<String> upload(@RequestParam("file") MultipartFile file, @RequestParam("category") Category category) {
    try {
        if (ObjectUtils.isEmpty(file)) {
            return ResponseEntity.ok().body("The uploaded file cannot be empty");
        } else {
            return ResponseEntity.ok().body(service.saveFile(file, category.getName()));
        }
    } catch (Exception e) {
        log.error("[Upload Failed]", e);
        return ResponseEntity.badRequest().body(e.getMessage());
    }
}

@GetMapping(value = "/download", produces = MediaType.MULTIPART_FORM_DATA_VALUE)
@Operation(summary =  "Download a document by its name")
public ResponseEntity<String> download(HttpServletResponse response, @RequestParam("fileName") String fileName) {
    try {
        service.downLoad(response, fileName);
        return ResponseEntity.ok().body("SUCCESS");
    } catch (Exception e) {
        log.error("[Download Failed]", e.getMessage());
        return ResponseEntity.badRequest().body(e.getMessage());
    }
}

@GetMapping("/byCategory")
@Operation(summary =  "Get information about all documents in a category")
public ResponseEntity<List<FileMetaDomain>> getByCategory(@RequestParam("category") Category category) {
    List<FileMetaDomain> allFilesForCategory = service.getAllFilesForCategory(category.getName());
    return ResponseEntity.ok(allFilesForCategory);
}

}

我的枚举：

import lombok.AccessLevel;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.ToString;

@ToString
@AllArgsConstructor(access = AccessLevel.PRIVATE)
@Getter
public enum Category {

    CATEGORY1("Cat 1"),
    CATEGORY2("Cat 2"),
    CATEGORY3("Cat 3");

    private final String name;

}

然而，我的Swagger-UI看起来像这样：

​

如前所述，它适用于Postman (尽管此时响应只是一个空数组)：

​

Answer 1

重点是toString()方法覆盖。尝试删除@ToString注释。

您的Category应为：

import lombok.AccessLevel;
import lombok.AllArgsConstructor;
import lombok.Getter;

@AllArgsConstructor(access = AccessLevel.PRIVATE)
@Getter
public enum Category {

    CATEGORY1("Cat 1"),
    CATEGORY2("Cat 2"),
    CATEGORY3("Cat 3");

    private final String name;
}

然后swagger-ui将显示枚举值下拉列表：

​

​

更新:如果您需要保留toString()方法，则必须在控制器上丰富category参数描述。您的GET /byCategory端点代码应如下所示：

@GetMapping("/byCategory")
@Operation(summary =  "Get information about all documents in a category")
public ResponseEntity<List<FileMetaDomain>> getByCategory(@Parameter(name = "category", in = ParameterIn.QUERY, schema = @Schema(type = "string", allowableValues = {"CATEGORY1", "CATEGORY2", "CATEGORY3"})) Category category) {
    List<FileMetaDomain> allFilesForCategory = service.getAllFilesForCategory(category.getName());
    return ResponseEntity.ok(allFilesForCategory);
}