Swagger/OpenAPI and Spring Security

If your project uses Spring Security and you have added Swagger/OpenAPI to it, there is a little additional configuration you need to do in order to make your /v3/api-docs and swagger-ui.html pages work.

Enable Swagger URLs in Spring Security Project

To enable Swagger URLs in a RESTful Web Services project built with Spring Boot and Spring Security Framework, make the following configuration to your WebSecurity Java class which is annotated with @EnableWebSecurity annotation:

http
.authorizeHttpRequests()
.requestMatchers("/swagger-ui/**")
.permitAll();

Below is an example of my WebSecurity Java class with the needed configuration to enable Swagger URLs.

package com.appsdeveloperblog.webapp.security;

import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityCustomizer;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableWebSecurity
public class WebSecurity {
    
    @Bean
    public SecurityFilterChain configure(HttpSecurity http) throws Exception {

        http
        .authorizeHttpRequests()
        .requestMatchers("/swagger-ui/**")
        .permitAll();
        
        return http.build();
    }

    @Bean
    public WebSecurityCustomizer webSecurityCustomizer() {
        return (web) -> web.ignoring().requestMatchers("/v3/api-docs/**");
    }
    
}

Once you add the above-mentioned configuration to your WebSecurity Java class, it should help you get the /v3/api-docs and swagger-ui.html pages to start working. Do not forget to specify the path of the OpenAPI documentation and the Swagger UI in your application.properties file like this:

springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

Best Practices for Documenting REST APIs with Swagger

1. Use descriptive path and operation names – Path and operation names should accurately describe the resource and the action being performed. Use nouns for paths and verbs for operations.
2. Provide detailed descriptions – Use the “description” field to provide a detailed explanation of the operation, including any input parameters and their types, possible response codes, and any other relevant details.
3. Use common response codes – Use the HTTP response codes that are most commonly used for each operation. For example, use 200 for a successful operation, 400 for a bad request, 401 for unauthorized access, and so on.
4. Use examples – Use examples to show how to use the API and what kind of response to expect. Examples can be included in the “examples” field of the Swagger specification.
5. Validate input parameters – Use the “schema” field to validate input parameters. This ensures that the parameters meet the expected data type and format.
6. Group related operations – Group related operations together under a single path. This makes the API easier to navigate and understand.
7. Version your API – Version your API using the URL path. This ensures that changes to the API do not break existing clients.
8. Update documentation regularly – Keep the documentation up-to-date with any changes to the API. This ensures that clients always have accurate and relevant information.

Conclusion

In conclusion, documenting your RESTful APIs with Swagger/OpenAPI is an essential aspect of software development that can help streamline the API design and development process. With this tutorial, you have learned how to configure Swagger/OpenAPI with Spring Security to enable Swagger URLs. If you’re unsure about how to add Swagger/OpenAPI to your Spring Boot application, this tutorial Document Spring REST API with OpenAPI 3(Swagger) can help you out. Additionally, there are some video courses available below that can teach you more about Swagger/OpenAPI and how to use it.

Frequently asked questions

• What is Swagger, and why do I need it in my Spring Boot project?
  Swagger is a tool that helps developers design, document, and test APIs. It’s useful in Spring Boot projects to provide a user-friendly interface to interact with APIs.
• Why am I getting a 404 error when I try to access the /v2/api-docs or swagger-ui.html pages?
  A 404 error may occur if the requestMatchers() for Swagger URLs are not added correctly in the WebSecurity Java class.
• How can I customize the appearance of my Swagger documentation?
  You can customize the appearance of your Swagger documentation by modifying the configuration settings in the Docket bean of your Swagger configuration.
• What are the benefits of using Swagger in my Spring Boot project?
  Using Swagger in a Spring Boot project can save time by automating API documentation and testing, as well as providing a more intuitive interface for interacting with APIs.