在 springdoc-openapi-ui 中为 Bearer Token Authentication (JWT) 启用授权按钮

Question

如何在 springdoc-openapi-ui (OpenAPI 3.0 /swagger-ui.html) 中启用 "Authorize" 按钮以进行 Bearer Token 身份验证，例如 JWT。

Spring@Controller和@Configuration类需要加什么注解？

Answer 1

在 @Configuration bean 中使用注释 @io.swagger.v3.oas.annotations.security.SecurityScheme 为 OpenAPI 3.0 定义全局安全方案：

@Configuration
@OpenAPIDefinition(info = @Info(title = "My API", version = "v1"))
@SecurityScheme(
    name = "bearerAuth",
    type = SecuritySchemeType.HTTP,
    bearerFormat = "JWT",
    scheme = "bearer"
)
public class OpenApi30Config {

}

注释每个 @RestController 需要不记名令牌身份验证 (JWT) 的方法 @io.swagger.v3.oas.annotations.Operation 引用已定义的安全方案：

@Operation(summary = "My endpoint", security = @SecurityRequirement(name = "bearerAuth"))

Answer 2

我更喜欢使用 bean 初始化而不是注释。

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info; 
import io.swagger.v3.oas.models.security.SecurityRequirement; 
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.StringUtils;

@Configuration
public class OpenApi30Config {

  private final String moduleName;
  private final String apiVersion;

  public OpenApi30Config(
      @Value("${module-name}") String moduleName,
      @Value("${api-version}") String apiVersion) {
    this.moduleName = moduleName;
    this.apiVersion = apiVersion;
  }

  @Bean
  public OpenAPI customOpenAPI() {
    final String securitySchemeName = "bearerAuth";
    final String apiTitle = String.format("%s API", StringUtils.capitalize(moduleName));
    return new OpenAPI()
        .addSecurityItem(new SecurityRequirement().addList(securitySchemeName))
        .components(
            new Components()
                .addSecuritySchemes(securitySchemeName,
                    new SecurityScheme()
                        .name(securitySchemeName)
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT")
                )
        )
        .info(new Info().title(apiTitle).version(apiVersion));
  }
}

代码行

.addSecurityItem(new SecurityRequirement().addList(securitySchemeName))

允许添加全局安全模式并摆脱对每个@Operation 的写入安全方法。

Answer 3

如果您想避免使用 security 属性对 @RestController 中的每个 @Operation 进行注释，您可以在 class 级别添加它，影响每个操作你的控制器。

请不要忘记您的配置 bean 需要与另一个示例中的相同：

@Configuration
@OpenAPIDefinition(info = @Info(title = "My API", version = "v1"))
@SecurityScheme(
    name = "bearerAuth",
    type = SecuritySchemeType.HTTP,
    bearerFormat = "JWT",
    scheme = "bearer"
)
public class OpenApi30Config {
}

在 class 级别添加安全要求

您只需在那些 class 上使用 @SecurityRequirement(name = "bearerAuth")，您希望在其中限制 API 调用。请注意，这些注释是 继承的 ，因此您也可以将它们添加到任何界面。

创建带有所需注释的标记界面：

@SecurityRequirement(name = "bearerAuth")
public interface SecuredRestController {
}

将标记接口添加到那些您希望将限制应用于所有操作的控制器，例如：

@RestController
@RequestMapping("/hello")
public class HelloController implements SecuredController {

    @GetMapping
    public String hello() {
        return "Hello World";
    }

    @GetMapping("/{name}")
    public String helloWithName(@PathVariable String name) {
        return "Hello " + name;
    }

}

您可以在标记界面不说的情况下执行此操作：

@RestController
@RequestMapping("/hello")
@SecurityRequirement(name = "bearerAuth")
public class HelloController {
...
}

现在您的操作都受到保护并且需要 JWT 令牌。

在方法级别添加安全要求

正如另一个 post 中所说，您必须将 @SecurityRequirement 添加到方法的 @Operation 注释中。

@RestController
@RequestMapping("/hello")
public class HelloController {

    @GetMapping
    @Operation(summary = "My endpoint", security = @SecurityRequirement(name = "bearerAuth"))
    public String hello() {
        return "Hello World";
    }

    @GetMapping("/{name}")
    public String helloWithName(@PathVariable String name) {
        return "Hello " + name;
    }

}

这只限制了第一个操作，而不限制第二个操作。

在 springdoc-openapi-ui 中为 Bearer Token Authentication (JWT) 启用授权按钮

Enable Authorize button in springdoc-openapi-ui for Bearer Token Authentication (JWT)

java

spring

jwt

openapi

springdoc

在 class 级别添加安全要求

在方法级别添加安全要求