Spring boot Swagger 3 - OpenApi 文档中默认不显示控制器摘要

Question

默认情况下，API 方法名称在 Swagger2

中显示为摘要

但是，默认情况下 OpenApi3 中不显示。

如何配置此属性？不在每个控制器端点使用 @Operation(summary = "Summary")。

依赖关系：implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.5.10'

Answer 1

OpenAPI v3 中的方法名称由 operationId 字段表示。

Springdoc 默认不显示 operationId。要启用它，您需要在应用程序的属性文件中将以下属性设置为 true（例如，application.properties、application.yml 等）

springdoc.swagger-ui.displayOperationId=true

尽管 operationId 可以像这样明确指定

@Operation(summary = "Some method", operationId = "Operation 1", description = "Some Description")

这给你输出如下

但是如果您没有明确指定 operationId 字段，它默认为方法名称（这是您想要的输出）。

考虑以下代码示例

@PostMapping(value = "/create/{userId}", consumes = {MULTIPART_FORM_DATA_VALUE, IMAGE_PNG_VALUE, IMAGE_JPEG_VALUE, MULTIPART_MIXED_VALUE}, produces = {TEXT_PLAIN_VALUE})
@Operation(summary = "Save File", description = "Save the file to the disk")
public ResponseEntity<Object> saveFile(
    @Parameter(description = "ID of the user") 
    @PathVariable(value = "userId") final String userId,
) {
    return null;
}

@GetMapping(value = "/get", produces = MediaType.IMAGE_PNG_VALUE)
@ApiResponse(responseCode = "200", description = "OK", content = {@Content(schema = @Schema(type = "string", format = "binary"))})
public ResponseEntity<byte[]> getFile() {
    return null;
}

以上代码片段将给出以下输出

Spring boot Swagger 3 - OpenApi 文档中默认不显示控制器摘要

Spring boot Swagger 3 - Controller summary is not getting displayed by default in OpenApi documentation

java

spring-boot

swagger-ui

openapi

springdoc-openapi-ui