When building a Spring Boot API with JWT authentication, having an easy way to test secured endpoints is essential. One common challenge is enabling the Authorize button in springdoc‑openapi‑ui (Swagger UI) so that you can use Bearer Token authentication seamlessly. In this guide, we’ll walk through several solutions for setting up Bearer Token authentication in your OpenAPI 3.0 documentation.
Why Enable the Authorize Button?
By default, the Swagger UI generated by springdoc‑openapi‑ui may not offer an easy way to test endpoints secured by JWT tokens. Enabling the Authorize button allows developers and testers to provide the JWT token directly in the UI, making it simple to execute secure API calls without external tools.
Solution 1: Bean Initialization Approach
One straightforward solution is to initialize a global security scheme using a Spring bean. This method adds the security configuration programmatically and applies it to all endpoints without the need for annotations on each method.
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));
}
}
Key Point: The line.addSecurityItem(new SecurityRequirement().addList(securitySchemeName))
ensures that all operations automatically include the security scheme without adding annotations to every method.
Solution 2: Annotation-Based Global Security Scheme
If you prefer using annotations, you can define a global security scheme in your configuration class. This approach uses the @SecurityScheme annotation to configure JWT settings.
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import org.springframework.context.annotation.Configuration;
@Configuration
@OpenAPIDefinition(info = @Info(title = "My API", version = "v1"))
@SecurityScheme(
name = "bearerAuth",
type = SecuritySchemeType.HTTP,
bearerFormat = "JWT",
scheme = "bearer"
)
public class OpenApi30Config {
}
Now, simply annotate your controller methods with:
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class ExampleController {
@GetMapping("/secured")
@Operation(summary = "Secured endpoint", security = @SecurityRequirement(name = "bearerAuth"))
public String securedEndpoint() {
return "This endpoint requires a JWT token";
}
}
Solution 3: Class-Level Security Annotation
To avoid repetitive annotations on each method, you can apply security at the controller class level. This ensures that every endpoint in the controller requires a valid JWT token.
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/hello")
@SecurityRequirement(name = "bearerAuth")
public class HelloController {
@GetMapping
public String hello() {
return "Hello World";
}
@GetMapping("/{name}")
public String helloWithName(@PathVariable String name) {
return "Hello " + name;
}
}
Alternatively, you can create a marker interface:
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
@SecurityRequirement(name = "bearerAuth")
public interface SecuredRestController {
}
Then implement it in your controllers:
@RestController
@RequestMapping("/hello")
public class HelloController implements SecuredRestController {
@GetMapping
public String hello() {
return "Hello World";
}
}
Solution 4: Global Security Configuration with OpenAPIDefinition
You can also define a global security requirement across all controllers using the @OpenAPIDefinition annotation:
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeIn;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import org.springframework.context.annotation.Configuration;
@Configuration
@OpenAPIDefinition(
info = @Info(title = "Channel API", version = "v1"),
security = @SecurityRequirement(name = "bearerAuth")
)
@SecurityScheme(
name = "bearerAuth",
type = SecuritySchemeType.HTTP,
bearerFormat = "JWT",
scheme = "bearer",
in = SecuritySchemeIn.HEADER
)
public class OpenApiConfig {
}
This setup applies the security requirement globally, so you don’t need to annotate individual controllers or methods.
Solution 5: Custom OpenAPI Customizer
For a cleaner approach, you can implement an OpenApiCustomiser component to programmatically add your security scheme. This method keeps your configuration centralized and avoids repetitive annotations.
package com.example.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));
}
}
Best Practices and Guidelines
When configuring JWT authentication in springdoc‑openapi‑ui, keep the following best practices in mind:
- Centralize Configuration: Whether using bean initialization or annotations, centralize your security configuration to avoid repetitive code.
- Global Security: Use global security requirements to ensure all endpoints are protected without manually annotating each one.
- Clean Code: Maintain readability and avoid cluttering your controllers with security annotations when possible.
- Keywords:
Use keywords such asspringdoc-openapi-ui,JWT authentication,Bearer Token,Swagger UI,OpenAPI 3.0,Enable Authorize Button,Spring Boot security, andglobal security scheme.
This guide provides multiple solutions to suit your project’s needs. By following these steps, you can easily enable the Authorize button in springdoc‑openapi‑ui, allowing developers and testers to work with JWT-secured APIs efficiently.
Implement one of these solutions to enhance your Swagger UI experience and improve your API testing workflow. Happy coding!
This post is designed to be informative, spam-free, and optimized for search engines. Let me know if you need additional details or modifications!
