如何为 springdoc-openapi 端点调用添加带有授权的标头

Question

Swagger2 (springfox) 合作过：

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build()
        .useDefaultResponseMessages(false)
        .globalOperationParameters(Collections.singletonList(getAuthHeader()));
}

private Parameter getAuthHeader() {
    return new ParameterBuilder()
        .parameterType("header")
        .name("Authorization")
        .modelRef(new ModelRef("string"))
        .defaultValue(getBase64EncodedCredentials())
        .build();
}

private String getBase64EncodedCredentials() {
    String auth = authUser.getUser() + ":" + authUser.getPassword();
    byte[] encodedAuth = Base64.encode(auth.getBytes(StandardCharsets.UTF_8));
    return "Basic " + new String(encodedAuth, Charset.defaultCharset());
}

Springdoc-openapi：

@Bean
public OpenAPI getOpenAPI() {
    return new OpenAPI().components(new Components()
        .addHeaders("Authorization", new Header().description("Auth header").schema(new StringSchema()._default(getBase64EncodedCredentials()))));
}

我无法为 springdoc-openapi 实现它。看来标题不起作用。

Answer 1

将参数定义添加到自定义 OpenAPI bean 将不起作用，因为参数不会传播到操作定义。您可以使用 OperationCustomizer 实现您的目标：

@Bean
public OperationCustomizer customize() {
    return (operation, handlerMethod) -> operation.addParametersItem(
            new Parameter()
                    .in("header")
                    .required(true)
                    .description("myCustomHeader")
                    .name("myCustomHeader"));
}

OperationCustomizer接口是在springdoc-openapi 1.2.22中引入的。

Answer 2

为了使Authorization标头发挥作用，还需要将其包含security在规范的根中。

例如，下面的代码将在Authorization标头中设置 JWT 不记名令牌。

@Bean
public OpenAPI customOpenAPI(@Value("${openapi.service.title}") String serviceTitle, @Value("${openapi.service.version}") String serviceVersion) {
    final String securitySchemeName = "bearerAuth";
    return new OpenAPI()
            .components(
                    new Components()
                            .addSecuritySchemes(securitySchemeName,
                                    new SecurityScheme()
                                            .type(SecurityScheme.Type.HTTP)
                                            .scheme("bearer")
                                            .bearerFormat("JWT")
                            )
            )
            .security(List.of(new SecurityRequirement().addList(securitySchemeName)))
            .info(new Info().title(serviceTitle).version(serviceVersion));
}

生成的规范 yml 如下 -

security:
  - bearerAuth: []
...
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

因此，根据上述规范，以下部分导致Authorization标题

  security:
    - bearerAuth: []

Answer 3

您所描述的行为与 springdoc-openapi 无关。但对于 swagger-ui 来说，它也遵循 OpenAPI 规范：

• https://github.com/swagger-api/swagger-ui/issues/5715

  OpenAPI 3 规范不允许显式添加 Authorization header。欲了解更多信息，请阅读：

  Note: Header parameters named Accept, Content-Type and Authorization are not allowed. To describe these headers

  请阅读：

• https://swagger.io/docs/specification/describing-parameters/#header-parameters。