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

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

Answer 2

查看 swagger-ui 中每个端点的更多详细信息，例如 openapi3 yaml 规范文件中的元数据、注释和描述；您可以通过添加以下依赖项来包含 javadoc：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-javadoc</artifactId>
    <version>1.6.12</version>
</dependency>   

然后添加下面的插件：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <annotationProcessorPaths>
                    <path>
                        <groupId>com.github.therapi</groupId>
                        <artifactId>therapi-runtime-javadoc-scribe</artifactId>
                        <version>0.15.0</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

参见https://springdoc.org/#javadoc-support