Adding Swagger to Spring Boot REST API

 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

xml

Copy

Download

Run

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

Gradle

groovy

Copy

Download

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

2. Basic Configuration

Create a configuration class:

java

Copy

Download

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:

java

Copy

Download

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:

Copy

Download

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

Or for the OpenAPI JSON:

Copy

Download

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

5. Advanced Configuration

Custom Path

In application.properties:

properties

Copy

Download

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

Security Integration

If using Spring Security:

java

Copy

Download

@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:

java

Copy

Download

@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:

java

Copy

Download

@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:

java

Copy

Download

@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.