SoFunction
Updated on 2025-05-23

Detailed explanation of Swagger2 and Springdoc integration and use

The following isSwagger2Migrate toSpringdoc(Support OpenAPI 3) Integration and usage guide covering key steps, configuration examples and considerations:

1. Depend on configuration

SpringdocIs a modern tool that supports the OpenAPI 3 specification and is suitable for Spring Boot projects.

The following dependencies need to be replaced or added:

<!-- Maven rely -->
<dependency>
    <groupId></groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version> <!-- Use the latest version -->
</dependency>

Notice: If the project is usedspringfox-swagger2, the relevant dependencies need to be removed to avoid conflicts.

2. Basic configuration

2.1 Enable Springdoc

Springdoc is automatically configured without explicitly enabling annotations.

existorBasic configuration information:

# 
=true
=/api-docs
=/
=1.0.0
-produces-media-type=application/json

2.2 Customize OpenAPI information

Define API metadata through Java configuration classes:

import .;
import .;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("API Documentation")
                        .version("1.0")
                        .description("OpenAPI Documentation Based on Springdoc")
                        .contact(new Contact().name("Developer").email("dev@"))
                        .license(new License().name("Apache 2.0")));
    }
}

3. Annotation usage

Springdoc.Annotation substitution。

Common annotation comparison table:

Swagger2 Annotation Springdoc Annotations use
@Api @Tag Controller classification description
@ApiOperation @Operation Interface method description
@ApiParam @Parameter Method parameter description
@ApiModel @Schema Data model description
@ApiModelProperty @Schema Model field description
@ApiResponse @ApiResponse Interface response description

Sample code:

import .;
import .;
import .;

@RestController
@Tag(name = "User Management", description = "User-related operation interface")
@RequestMapping("/users")
public class UserController {

    @Operation(summary = "Get user details", description = "Query details based on user ID")
    @GetMapping("/{id}")
    public User getUser(
        @Parameter(description = "User ID", required = true) @PathVariable Long id) {
        // Business logic    }
}

4. Access the Swagger UI

After starting the application, access the interactive document interface via the following URL:

  • Swagger UI: http://localhost:8080/
  • OpenAPI JSON: http://localhost:8080/v3/api-docs

5. Advanced configuration

5.1 Multiple sets of APIs

Configure multiple sets of API documentation for different modules:

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

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

5.2 Security Configuration

When integrating JWT or OAuth2, add security solutions:

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .components(new Components()
                    .addSecuritySchemes("bearerAuth", 
                        new SecurityScheme()
                            .type()
                            .scheme("bearer")
                            .bearerFormat("JWT")))
            .info(/* Omitted */);
}

6. Integrate with Spring Security

Ensure Spring Security allows access to document endpoints:

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
                .anyRequest().authenticated()
            );
        return ();
    }
}

7. Migration precautions

  1. Remove old dependencies: Completely clearedspringfox-swagger2andswagger-annotations。
  2. Annotation replacement: Global replacement package path → .。
  3. Path changes: The default path to Swagger UI from/swagger-ui/Become/。

8. Frequently Asked Questions

Q1: The document page cannot be loaded?

  • Check for dependency conflicts: Make sure nospringfoxResidual dependence.
  • Verify path configuration:confirmNot covered.

Q2: The annotation has not taken effect?

  • Package path correctness: Confirm use.Notes below.
  • Method signature matching：@ParameterNeed to modify the parameters directly or cooperate@RequestParamuse.

With the above steps, you can quickly migrate your project from Swagger2 to Springdoc and take advantage of the new features of OpenAPI 3.

Summarize

The above is personal experience. I hope you can give you a reference and I hope you can support me more.