Master SpringDoc: The Modern Swagger Alternative for Spring Boot 3

SpringDoc Overview

SpringDoc is an API documentation tool that integrates with Spring Boot and is built on OpenAPI 3. It has over 3.5K stars on GitHub, receives frequent updates, and supports Spring WebMvc, WebFlux, Rest, and Native projects, making it a powerful Swagger alternative.

Usage

The following sections cover basic usage and integration with Spring Security.

Integration and Configuration

Add the SpringDoc dependency to pom.xml:

<!--SpringDoc related dependency-->
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>${springdoc-openapi.version}</version>
</dependency>

Then configure SpringDoc in application.yml:

springdoc:
  swagger-ui:
    # Change Swagger UI path
    path: /swagger-ui.html
    # Enable Swagger UI
    enabled: true
  api-docs:
    # Change api-docs path
    path: /v3/api-docs
    # Enable api-docs
    enabled: true
  group-configs:
    - group: 'brand'
      paths-to-match: '/brand/**'
      packages-to-scan: com.macro.blog.springdoc.controller
    - group: 'admin'
      paths-to-match: '/admin/**'
      packages-to-scan: com.macro.blog.springdoc.controller
    default-flat-param-object: false

Comparison with SpringFox

@Api

→ @Tag (class level) @ApiIgnore → @Parameter(hidden = true) / @Operation(hidden = true) / @Hidden (ignore class) @ApiImplicitParam → @Parameter (method parameter) @ApiModel → @Schema (entity class) @ApiModelProperty → @Schema (entity field) @ApiOperation → @Operation (method description) @ApiParam → @Parameter (method parameter description) @ApiResponse → ApiResponse(responseCode = "404", description = "foo") (response description)

Basic Usage Example

This example uses the brand management module from the mall project.

/**
 * @author macrozheng
 * @description SpringDoc API documentation configuration
 * @date 2025/8/12
 */
@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI mallTinyOpenAPI() {
        return new OpenAPI()
            .info(new Info().title("SpringDoc API").description("SpringDoc API documentation demo").version("v1.0.0")
                .license(new License().name("Apache 2.0").url("https://github.com/macrozheng/mall-learning")))
            .externalDocs(new ExternalDocumentation()
                .description("SpringBoot e‑commerce project mall (60K+ stars) full documentation")
                .url("https://www.macrozheng.com"));
    }
}

@Tag(name = "PmsBrandController", description = "Product brand management")
@RestController
@RequestMapping("/brand")
public class PmsBrandController {
    @Autowired
    private PmsBrandService brandService;

    @Operation(summary = "Get all brand list", description = "Requires login")
    @GetMapping("/listAll")
    public CommonResult<List<PmsBrand>> listAll() {
        return CommonResult.success(brandService.listAll());
    }

    @Operation(summary = "Add brand")
    @PostMapping("/create")
    public CommonResult create(@RequestBody PmsBrand pmsBrand) {
        int count = brandService.create(pmsBrand);
        return count == 1 ? CommonResult.success(pmsBrand) : CommonResult.failed("Operation failed");
    }

    // Additional CRUD methods omitted for brevity
}

@Data
public class PmsBrand {
    private Long id;
    private String name;
    @Schema(title = "First letter")
    private String firstLetter;
    private Integer sort;
    @Schema(title = "Is manufacturer: 0‑No, 1‑Yes")
    private Integer factoryStatus;
    private Integer showStatus;
    @Schema(title = "Product count")
    private Integer productCount;
    @Schema(title = "Product comment count")
    private Integer productCommentCount;
    @Schema(title = "Brand logo")
    private String logo;
    @Schema(title = "Big picture")
    private String bigPic;
    @Schema(title = "Brand story")
    private String brandStory;
}

Combining with Spring Security

When authentication is required, Spring Security can be integrated. The OpenAPI object is extended with a JWT security scheme:

/**
 * @author macrozheng
 * @description SpringDoc API documentation configuration with security
 * @date 2025/8/12
 */
@Configuration
public class SpringDocConfig {
    private static final String SECURITY_SCHEME_NAME = "Authorization";

    @Bean
    public OpenAPI mallTinyOpenAPI() {
        return new OpenAPI()
            .info(new Info().title("SpringDoc API").description("SpringDoc API documentation demo").version("v1.0.0")
                .license(new License().name("Apache 2.0").url("https://github.com/macrozheng/mall-learning")))
            .externalDocs(new ExternalDocumentation()
                .description("SpringBoot e‑commerce project mall (60K+ stars) full documentation")
                .url("https://www.macrozheng.com"))
            .addSecurityItem(new SecurityRequirement().addList(SECURITY_SCHEME_NAME))
            .components(new Components()
                .addSecuritySchemes(SECURITY_SCHEME_NAME,
                    new SecurityScheme()
                        .name(SECURITY_SCHEME_NAME)
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT"))));
    }
}

Testing

Start the application and open http://localhost:8088/swagger-ui.html.

Log in via the authentication endpoint using the default credentials admin:123456 to obtain a JWT token.

In Swagger UI, paste the token into the authorization header field without the Bearer prefix.

Authenticated endpoints can now be accessed; unauthenticated requests will return an error.

Conclusion

SpringDoc offers a low learning curve, full support for Spring Boot 3, and additional features such as WebFlux and native image compatibility, making it a superior choice over SpringFox for API documentation.

Project Links

SpringDoc repository: https://github.com/springdoc/springdoc-openapi

Example project source: https://github.com/macrozheng/spring-examples/tree/master/spring-springdoc