My View and Experience: swagger

Swagger (now part of the OpenAPI specification) is a powerful tool for documenting and testing your REST APIs. Here's how to integrate it with a Spring Boot application:

1. Add Dependencies

Add these to your pom.xml (Maven) or build.gradle (Gradle):

Maven

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version> <!-- Check for latest version -->
</dependency>

Gradle

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

2. Basic Configuration

Create a configuration class:

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("Training Service API")
                        .description("Spring Boot REST API for Training Management")
                        .version("v1.0.0")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")));
    }
}

3. Annotate Your Controllers

Add Swagger annotations to document your endpoints:

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@RequestMapping("/api/trainings")
@Tag(name = "Training Controller", description = "Operations related to training sessions")
public class TrainingController {

    @GetMapping
    @Operation(summary = "Get all trainings", description = "Returns list of all available trainings")
    public ResponseEntity<List<Training>> getAllTrainings() {
        // implementation
    }

    @PostMapping
    @Operation(summary = "Create new training", description = "Creates a new training session")
    public ResponseEntity<Training> createTraining(@RequestBody TrainingDto trainingDto) {
        // implementation
    }
}

4. Access Swagger UI

After starting your application, access the UI at:

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

Or for the OpenAPI JSON:

http://localhost:8080/v3/api-docs

5. Advanced Configuration

Custom Path

In application.properties:

springdoc.swagger-ui.path=/api-docs
springdoc.api-docs.path=/api-docs.json

Security Integration

If using Spring Security:

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .antMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
            // other security config
    }
}

Model Documentation

Annotate your DTOs:

@Schema(description = "Training data transfer object")
public class TrainingDto {
    
    @Schema(description = "Unique identifier of the training", example = "123")
    private Long id;
    
    @Schema(description = "Training title", required = true, example = "Spring Boot Workshop")
    private String title;
    
    // getters and setters
}

6. Grouping APIs

For multiple API groups:

@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("training-public")
            .pathsToMatch("/api/trainings/**")
            .build();
}

@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
            .group("training-admin")
            .pathsToMatch("/api/admin/**")
            .build();
}

7. Versioning Support

Document API versions:

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .info(new Info()
            .title("Training API")
            .version("1.0")
            .description("API for training management")
            .termsOfService("http://swagger.io/terms/"))
        .externalDocs(new ExternalDocumentation()
            .description("Training API Wiki Documentation")
            .url("https://example.com/docs"));
}

8. Troubleshooting

Common Issues:

404 on Swagger UI: Ensure you're using the correct path (check springdoc.swagger-ui.path)
Missing endpoints: Verify your controllers are in a package scanned by Spring
Security blocking access: Configure security to permit Swagger paths

This setup provides:

Interactive API documentation
Automatic model documentation
Try-it-out functionality for endpoints
Support for OAuth2 and JWT (with additional configuration)

For the latest updates and features, always check the official documentation.

My View and Experience

Sunday, May 25, 2025

Adding Swagger to Spring Boot REST API