如何在springdoc-openapi-ui(OpenAPI 3.0
/swagger-ui.html
)中启用“授权”按钮,例如JWT的Bearer令牌认证。
哪些注释必须添加到Spring@Controller
和@Configuration
类?
我更倾向于使用 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上编写安全性。
使用注释@io.swagger.v3.oas.annotations.security.SecurityScheme
在@Configuration
bean中定义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 {
}
使用@io.swagger.v3.oas.annotations.Operation
注释每个@RestController
方法,要求Bearer Token身份验证(JWT),并引用定义的安全方案:
在@RestControler方法上添加@Operation注释,并参考定义的安全方案,要求Bearer Token身份验证(JWT)。
@Operation(summary = "My endpoint", security = @SecurityRequirement(name = "bearerAuth"))
如果您想避免在@RestController
中的每个@Operation
上注释security
属性,您可以在类级别添加此属性以影响控制器的每个操作。
请不要忘记您的配置bean需与其他示例中的相同:
@Configuration
@OpenAPIDefinition(info = @Info(title = "My API", version = "v1"))
@SecurityScheme(
name = "bearerAuth",
type = SecuritySchemeType.HTTP,
bearerFormat = "JWT",
scheme = "bearer"
)
public class OpenApi30Config {
}
只需在您希望限制API调用的那些类上使用@SecurityRequirement(name="bearerAuth")
。请注意,这些注释是继承的,因此您也可以将它们添加到任何接口中。
使用所需的注释创建标记接口:
@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 {
...
}
正如另一篇帖子中所说,您必须将@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;
}
}
package com.aliyun.horoscope.verse.configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springdoc.core.customizers.OpenApiCustomiser;
import org.springframework.stereotype.Component;
@Component
public class AuthOpenApiCustomizer implements OpenApiCustomiser {
@Override
public void customise(OpenAPI openApi) {
var securitySchemeName = "bearerAuth";
openApi.getComponents().addSecuritySchemes(securitySchemeName, new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT"));
openApi.addSecurityItem(new SecurityRequirement().addList(securitySchemeName));
}
}