Apply Default Global SecurityScheme in springdoc-openapi

1. Overview

In this tutorial, we’ll learn how to configure a default global security scheme and apply it as the default security requirement of the API using the springdoc-openapi library in a Spring MVC web application. Further, we’ll discuss how we can override these default security requirements.

The OpenAPI specification lets us define a set of security schemes for the API. We can configure the security requirements of the API globally or apply/remove them per endpoint.

2. Setup

As we are building a Maven project using Spring Boot, let’s explore the setup of the project. At the end of this section, we’ll have a simple web app.

2.1. Dependencies

The example has two dependencies. The first dependency is the spring-boot-starter-web. This is the main dependency to build the web app:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.1.5</version>
</dependency>

The other dependency is the springdoc-openapi-ui, which is the library that will render the documentation of the API in HTML, JSON, or YAML:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

2.2. Application Entry Point

Once the dependencies are ready, let’s define the entry point for the application.

We’ll use the @SpringBootApplication annotation to bootstrap the app and the SpringApplication helper class to launch it:

@SpringBootApplication
public class DefaultGlobalSecuritySchemeApplication {
    public static void main(String[] args) {
        SpringApplication.run(DefaultGlobalSecuritySchemeApplication.class, args);
    }
}

3. springdoc-openapi Base Configuration

Once we have the Spring MVC configured, let’s look at the API semantic information.

We’ll define the default global security scheme and the API metadata by adding springdoc-openapi annotations to the DefaultGlobalSecuritySchemeApplication class. To define the global security scheme, we’ll use the @SecurityScheme annotation:

@SecurityScheme(type = SecuritySchemeType.APIKEY, name = "api_key", in = SecuritySchemeIn.HEADER)

We’ve chosen an APIKEY security scheme type, but we could configure other security schemes, for instance, JWT. After defining the security scheme, we’ll add the metadata and establish the default security requirement for the API. We do this using the @OpenApiDefinition annotation:

@OpenAPIDefinition(info = @Info(title = "Apply Default Global SecurityScheme in springdoc-openapi", version = "1.0.0"), security = { @SecurityRequirement(name = "api_key") })

Here, the info attribute defines the API metadata. Furthermore, the security attribute determines the default global security requirements.

Let’s see what the HTML documentation will look like with the annotations. We’ll see the metadata and a security button that will apply to the whole API:

4. Controllers

Now that we have configured the Spring framework and the springdoc-openapi library, let’s add one REST controller to the context base path. To achieve this, we’ll use the @RestController and @RequestMapping annotations:

@RestController
@RequestMapping("/")
public class DefaultGlobalSecuritySchemeOpenApiController {
    ...
}

After that, we’ll define two endpoints or paths.

The first endpoint will be the /login endpoint. It’ll receive the user credentials and authenticate the user. If the authentication succeeds, the endpoint will return a token.

The other endpoint of the API is the /ping endpoint and requires the token generated by the /login method. Before performing the request, the method validates the token and checks if the user is authorized.

In summary, the /login endpoint authenticates the user and provides a token. The /ping endpoint receives the token returned by the /login endpoint and checks that it’s valid and that the user can perform the operation.

4.1. login() Method

This method won’t have any security requirements. Therefore, we need to override the default security requirement configuration.

First of all, we need to tell Spring that this is an endpoint of our API, so we’ll add the annotation @RequestMapping to configure the endpoint:

@RequestMapping(method = RequestMethod.POST, value = "/login", produces = { "application/json" }, consumes = { "application/json" })

After that, we need to add semantic information to the endpoint. So we’ll use the @Operation and @SecurityRequirements annotations. The @Operation will define the endpoint and the @SecurityRequirements will define the specific set of security requirements that applies to the endpoint:

@Operation(operationId = "login", responses = {
    @ApiResponse(responseCode = "200", description = "api_key to be used in the secured-ping endpoint", content = { @Content(mediaType = "application/json", schema = @Schema(implementation = TokenDto.class)) }),
    @ApiResponse(responseCode = "401", description = "Unauthorized request", content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ApplicationExceptionDto.class)) }) })
@SecurityRequirements()

For instance, here’s the HTML documentation for the response with status code 200:

Finally, let’s see the login() method’s signature:

public ResponseEntity login(@Parameter(name = "LoginDto", description = "Login") @Valid @RequestBody(required = true) LoginDto loginDto) {
    ...
}

As we can see, the body of the API request receives a LoginDto instance. We also must decorate the DTOs with semantic information to display the information in the documentation:

public class LoginDto {
    private String user;
    private String pass;

    ...

    @Schema(name = "user", required = true)
    public String getUser() {
        return user;
    }

    @Schema(name = "pass", required = true)
    public String getPass() {
        return pass;
    }
}

Here we can see what the /login endpoint HTML documentation will look like:

4.2. ping() Method

At this point, we’ll define the ping() method. The ping() method will use the default global security scheme:

@Operation(operationId = "ping", responses = {
    @ApiResponse(responseCode = "200", description = "Ping that needs an api_key attribute in the header", content = {
        @Content(mediaType = "application/json", schema = @Schema(implementation = PingResponseDto.class), examples = { @ExampleObject(value = "{ pong: '2022-06-17T18:30:33.465+02:00' }") }) }),
    @ApiResponse(responseCode = "401", description = "Unauthorized request", content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ApplicationExceptionDto.class)) }),
    @ApiResponse(responseCode = "403", description = "Forbidden request", content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ApplicationExceptionDto.class)) }) })
@RequestMapping(method = RequestMethod.GET, value = "/ping", produces = { "application/json" })
public ResponseEntity ping(@RequestHeader(name = "api_key", required = false) String api_key) {
    ...
}

The main difference between the login() and ping() methods is in the security requirement that will be applied. The login() won’t have any security requirement at all, but the ping() method will have the security defined at the API level. So, the HTML documentation will represent the situation showing a lock only for the /ping endpoint:

5. REST API Documentation URLs

At this point, we have the Spring MVC web app ready, and we can start the server:

mvn spring-boot:run -Dstart-class="com.baeldung.defaultglobalsecurityscheme.DefaultGlobalSecuritySchemeApplication"

Once the server is ready, we can see the HTML documentation, as shown in the previous examples, at the http://localhost:8080/swagger-ui-custom.html URL.

The JSON version of the API definition is found at http://localhost:8080/api-docs and the YAML version at http://localhost:8080/api-docs.yaml.

These outputs can be used to build clients or servers of the API in different languages using the swagger-codegen-maven-plugin.

6. Conclusion

In this article, we’ve learned how to use the springdoc-openapi library to define a default global security scheme. Also, we saw how to apply it as the default security requirement to the API. Furthermore, we’ve learned how to change the default security requirement for a particular endpoint.

Another thing we’ve discovered is that we can automate code generation using the JSON and YAML outputs from the springdoc-openapi.