以编程方式添加安全方案时，架构将从组件中消失

Question

我最近从Springfox转换为Springdoc-openapi，用于为我的SpringBoot Rest API服务生成openapi。

一切都很顺利，直到我添加了一个安全方案。一旦我这样做了，我的方案就不再出现了，SwaggerUI页面上出现了一个错误：

Could not resolve reference: Could not resolve pointer: /components/schemas/Ping does not exist in document

我正在以编程方式设置我的配置，并且有两个组。

我正在使用Spring Boot v2.4.0和springdoc openapi ui v1.5.1

我的pom.xml片段：

<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.5.1</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-hateoas</artifactId>
<version>1.5.1</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-security</artifactId>
<version>1.5.1</version>
</dependency>

配置中的代码段：

@Bean
public GroupedOpenApi apiV1() {
String[] paths = {"/v1/**"};
String[] packagesToScan = {"com.test.controller"};
return GroupedOpenApi.builder()
.group("v1")
.packagesToScan(packagesToScan)
.pathsToMatch(paths)
.addOpenApiCustomiser(buildV1OpenAPI())
.build();
}
@Bean
public GroupedOpenApi apiV2() {
String[] paths = {"/v2/**"};
String[] packagesToScan = {"com.test.controller"};
return GroupedOpenApi.builder()
.group("v2")
.packagesToScan(packagesToScan)
.pathsToMatch(paths)
.addOpenApiCustomiser(buildV2OpenAPI())
.build();
}
public OpenApiCustomiser buildV1OpenAPI() {
return openApi -> openApi.info(apiInfo().version("v1"));
}
public OpenApiCustomiser buildV2OpenAPI() {
final String securitySchemeName = "Access Token";
return openApi -> openApi.info(apiInfo().version("v2"))
.addSecurityItem(new SecurityRequirement().addList(securitySchemeName))
.components(new Components().addSecuritySchemes(securitySchemeName, new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.HEADER)
.name(HttpHeaders.AUTHORIZATION)));
}
// Describe the apis
private Info apiInfo() {
return new Info()
.title("Title")
.description("API Description");
}

对于我的v1组来说，一切都很好。我的模式出现在Swagger UI页面上，我在生成的api文档的组件部分看到了它们。

"components": {
"schemas": {
"ApplicationErrorResponse": {
...
}
},
"Ping": {
...
}
}
}

对于我的v2组，不会生成架构。

"components": {
"securitySchemes": {
"Access Token": {
"type": "apiKey",
"name": "Authorization",
"in": "header"
}
}
}

知道为什么在以编程方式将安全方案添加到OpenAPI组件时，我的架构没有自动扫描和添加吗？我的配置中遗漏了什么吗？

这是我的控制器中的请求映射。

@Operation(summary = "Verify API and backend connectivity",
description = "Confirm connectivity to the backend, as well and verify API service is running.")
@OkResponse
@GetMapping(value = API_VERSION_2 + "/ping", produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<Ping> getPingV2(HttpServletRequest request) {

}

这是我的@OkResponse注释：

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
@Documented
@ApiResponse(responseCode = HTTP_200,
description = HTTP_200_OK,
headers = {
@Header(name = CONTENT_VERSION_HEADER, description = CONTENT_VERSION_HEADER_DESCRIPTION, schema = @Schema(type = "string")),
@Header(name = DEPRECATION_MESSAGE_HEADER, description = DEPRECATION_MESSAGE_HEADER_DESCRIPTION, schema = @Schema(type = "string")),
@Header(name = DESCRIPTION_HEADER, description = DESCRIPTION_HEADER_DESCRIPTION, schema = @Schema(type = "string"))
})
public @interface OkResponse {
}

我的v1映射定义类似。

Answer 1

因此，当仅依赖OpenApiCustomiser创建OpenAPI时，扫描的组件会被忽略，或者至少只被自定义程序中指定的组件覆盖(我也可以通过编程添加所有模式，但维护起来会非常麻烦(。

将我的配置更改为以下解决了我的问题：

@Bean
public OpenAPI customOpenAPI() {
final String securitySchemeName = "Access Token";
return new OpenAPI()
.addSecurityItem(new SecurityRequirement().addList(securitySchemeName))
.components(new Components().addSecuritySchemes(securitySchemeName, new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.HEADER)
.name(HttpHeaders.AUTHORIZATION)))
.info(apiInfo());
}
@Bean
public GroupedOpenApi apiV1() {
String[] paths = {"/v1/**"};
String[] packagesToScan = {"com.test.controller"};
return GroupedOpenApi.builder()
.group("v1")
.packagesToScan(packagesToScan)
.pathsToMatch(paths)
.addOpenApiCustomiser(buildV1OpenAPI())
.build();
}
@Bean
public GroupedOpenApi apiV2() {
String[] paths = {"/v2/**"};
String[] packagesToScan = {"com.test.controller"};
return GroupedOpenApi.builder()
.group("v2")
.packagesToScan(packagesToScan)
.pathsToMatch(paths)
.addOpenApiCustomiser(buildV2OpenAPI())
.build();
}
public OpenApiCustomiser buildV1OpenAPI() {
return openApi -> openApi.info(openApi.getInfo().version("v1"));
}
public OpenApiCustomiser buildV2OpenAPI() {
return openApi -> openApi.info(openApi.getInfo().version("v2"));
}
// Describe the apis
private Info apiInfo() {
return new Info()
.title("Title")
.description("API Description.");
}

虽然从技术上讲，这也将授权按钮和安全方案添加到v1组中，但它可以被忽略，因为这些API端点无论如何都不安全(内部API，它们应该很快就会消失(。

可能是更好的解决方案，因为组之间的信息基本相同。

Answer 2

与其创建新组件，不如修改它们：

public OpenApiCustomiser buildV2OpenAPI() {
final String securitySchemeName = "Access Token";
return openApi -> {
openApi.info(apiInfo().version("v2"))
.addSecurityItem(new SecurityRequirement().addList(securitySchemeName));

openApi.getComponents().addSecuritySchemes(securitySchemeName, new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.HEADER)
.name(HttpHeaders.AUTHORIZATION));
return openApi;

};
}

Answer 3

在不创建新组件对象的情况下修复了问题，尝试过kotlin。

@Bean
fun publicApiV1(): GroupedOpenApi = GroupedOpenApi.builder()
.group("service-name")
.pathsToMatch("/v1/**")
.addOpenApiCustomiser(publicApiCustomizer("v1"))
.build()
fun publicApiCustomizer(version: String): OpenApiCustomiser? {
return OpenApiCustomiser { openApi: OpenAPI ->
openApi.addSecurityItem(SecurityRequirement().addList(SECURITY_SCHEME_NAME))
.info(Info().title("title name").version(version))
.also {
it.components.addSecuritySchemes(
SECURITY_SCHEME_NAME,
SecurityScheme()
.`in`(HEADER)
.type(HTTP)
.scheme(SCHEME)
.name(SECURITY_SCHEME_NAME)
.bearerFormat(BEARER_FORMAT)
)
}
}
}
companion object {
private const val SECURITY_SCHEME_NAME = "bearerAuth"
private const val SCHEME = "bearer"
private const val BEARER_FORMAT = "JWT"
}