Comprehensive Guide to OpenAPI Swagger Integration in Spring Boot with Spring Security JWT

Introduction:

This comprehensive guide walks you through the process of integrating OpenAPI Swagger with a Spring Boot 3 project, while seamlessly incorporating Spring Security JWT for enhanced security. OpenAPI Swagger serves as a powerful tool for API documentation, aiding developers in understanding, testing, and interacting with your API effortlessly.

What is OpenAPI Swagger?

OpenAPI Swagger is an industry-standard specification for building APIs. It provides a language-agnostic interface to describe the functionality of your RESTful services. Swagger tools allow developers to generate interactive documentation, client SDKs, and even server stubs based on your API specifications.

Key Features:

• Interactive Documentation: Swagger UI provides an interactive and user-friendly interface, allowing developers to explore and test API endpoints in real-time.

• Code Generation: Generate client libraries and server stubs in various programming languages directly from your API specifications.

• Consistency: Ensure consistency and alignment between API design and implementation by maintaining a single source of truth.

Step-by-Step Guide:

Step 1: Add the springdoc-openapi Dependency

Include the springdoc-openapi library in your project’s dependencies to enable seamless integration with Spring Boot.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

Step 2: Create OpenApiConfig Class

Create a configuration class (SwaggerConfig) to customize OpenAPI documentation and handle Spring Security JWT. Here we are implementing using java.

@Configuration
public class SwaggerConfig {
String schemeName = "bearerAuth";
String bearerFormat = "JWT";
String scheme = "bearer";
@Bean
public OpenAPI caseOpenAPI() {
        return new OpenAPI()
                  .addSecurityItem(new SecurityRequirement()
.addList(schemeName)).components(new Components()
                                  .addSecuritySchemes(
                                        schemeName, new SecurityScheme()
                                        .name(schemeName)
                                        .type(SecurityScheme.Type.HTTP)
                                        .bearerFormat(bearerFormat)
                                        .in(SecurityScheme.In.HEADER)
                                        .scheme(scheme)
                                  )
                  )
                  .info(new Info()
                              .title("Case Management Service")
                              .description("Claim Event Information")
                              .version("1.0")
                  );
        }
}

We can also implement the config using annotations provided by swagger.

@OpenAPIDefinition(
        info = @Info(
                title = "Claims Service",
                version = "1.0",
                description = "Claims Information"
        ),
        security = {
                @SecurityRequirement(name = "bearerAuth")
        }
)
@SecurityScheme(
        name = "bearerAuth",
        description = "JWT authentication",
        scheme = "bearer",
        type = SecuritySchemeType.HTTP,
        bearerFormat = "JWT",
        in = SecuritySchemeIn.HEADER
)
public class SwaggerConfig {
}

Step 3: Configure Swagger UI Optionally, customize the path to Swagger UI in your application.properties or application.yml file.

springdoc.swagger-ui.path=/custom/swagger-ui

Step 4: Configure Spring Security to Ignore Swagger UI URLs
Exclude specific URLs from Spring Security to allow public access to Swagger UI and API documentation.

// ... existing security configurations

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

With this update, the specified URLs (“/swagger-ui/” and “/v3/api-docs/”) will be ignored by Spring Security, allowing public access to the Swagger UI and API documentation.

Step 5: Run the Application

Start your Spring Boot application and access the Swagger UI to explore and test your API.

http://localhost:8080/custom/swagger-ui.html

Step 6: Explore API Documentation

Utilize the power of Swagger UI to interactively explore API endpoints, request parameters, and responses.

Conclusion:

By following these steps, we have successfully integrated OpenAPI Swagger with Spring Boot project, configured it to work with Spring Security JWT, and provided an interactive API documentation platform for development team.