How to Quickly Integrate SpringDoc OpenAPI into Spring Boot for Swagger Docs

1. Add Dependency

Select the proper Maven dependency based on your Spring Boot version.

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.7.0</version>
</dependency>

For Spring Boot 3.x use the starter module:

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

Note: Spring Boot 3.x runs on the Jakarta API and requires starter-webmvc-ui or starter-webflux-ui depending on the project type.

2. Access Documentation

Swagger UI: http://localhost:8080/swagger-ui.html or /swagger-ui/index.html OpenAPI JSON: http://localhost:8080/v3/api-docs OpenAPI YAML:

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

3. Sample Controller

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用户增删改查 API")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "获取用户详情", description = "根据用户 ID 获取用户信息")
    public String getUser(@PathVariable Long id) {
        return "用户ID：" + id;
    }

    @PostMapping
    @Operation(summary = "创建用户", description = "创建一个新用户")
    public String createUser(@RequestBody String user) {
        return "创建用户：" + user;
    }
}

4. Customize OpenAPI Document Information

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

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("用户管理 API 文档")
                .version("1.0")
                .description("这是一个基于 SpringDoc OpenAPI 生成的 API 文档示例")
                .contact(new Contact().name("Test").email("[email protected]"))
                .license(new License().name("Apache 2.0").url("http://springdoc.org")));
    }
}

5. Common Configuration Options

springdoc:
  api-docs:
    enabled: true   # Enable OpenAPI docs
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    operations-sorter: method   # Sort by HTTP method
    tags-sorter: alpha          # Sort tags alphabetically

6. Advanced Usage

API Grouping (multi‑module or versioned APIs)

springdoc:
  group-configs:
    - group: v1
      paths-to-match: /api/v1/**
    - group: v2
      paths-to-match: /api/v2/**

Access with /swagger-ui/index.html?configUrl=/v3/api-docs/v1 Hide Specific Endpoints

@Operation(hidden = true)
public String hiddenApi() { ... }

Generate Offline Documentation

curl http://localhost:8080/v3/api-docs > openapi.json

7. Compatibility Notes

If your project uses Spring Boot 2.x, you must stay on springdoc-openapi-ui 1.x.

Spring Boot 3.x requires the springdoc-openapi-starter-xxx-ui 2.x series.

For WebFlux projects, use starter-webflux-ui instead of starter-webmvc-ui.