SpringDoc基本使用的方法示例

更新時間：2025年07月22日 09:18:31 作者：墨鴉_Cormorant

SpringDoc是基于Spring Boot的現(xiàn)代化API文檔生成工具,下面就來介紹一下SpringDoc基本使用,具有一定的參考價值,感興趣的可以了解一下

核心特性與優(yōu)勢

開箱即用

僅需添加依賴，無需復(fù)雜配置即可自動生成文檔，支持 Spring WebMvc、WebFlux、Spring Security 及 Jakarta EE。
注解驅(qū)動

使用 JSR-303 規(guī)范注解（如 @Tag、@Operation）替代 SpringFox 專屬注解，降低學(xué)習(xí)成本。
動態(tài)兼容性

完美適配 Spring Boot 2.6+ 及 3.x（含 JDK 17+），解決 SpringFox 因停維護導(dǎo)致的不兼容問題。
多格式輸出

支持 JSON/YAML/HTML 格式文檔，并提供分組功能，可按模塊劃分接口（如公開 API 與內(nèi)部 API）。

集成與配置

依賴引入（Spring Boot 3.x）

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version> <!-- 官方穩(wěn)定版，兼容 Spring Boot 3.3.x:cite[2]:cite[8] -->
</dependency>

基礎(chǔ)配置（application.yml）

springdoc:
  swagger-ui:
    # 開啟 swagger-ui 文檔展示
    enabled: true
    # UI訪問路徑
    path: /swagger-ui.html
    # 標簽排序方式
    tags-sorter: alpha
    # 操作排序方式
    operations-sorter: alpha
    # 保持認證狀態(tài)
    persistAuthorization: true
    # 禁用示例接口
    disable-swagger-default-url: true
  api-docs:
    # 開啟 OpenAPI 展示
    enabled: true
    # OpenAPI JSON路徑
    path: /v3/api-docs
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  cache:
    # 關(guān)閉文檔緩存
    disabled: false
  # 顯示actuator端點
  show-actuator: false
  # 推薦保持默認，顯示結(jié)構(gòu)化參數(shù)
  # default-flat-param-object: true
  # 允許在文檔中展示 Spring MVC 的 ModelAndView 返回類型
  model-and-view-allowed: true
  # 推薦關(guān)閉以確保文檔精確性
  override-with-generic-response: false

全局信息配置類（可選）

@Configuration
@OpenAPIDefinition(
  info = @Info(title = "項目API文檔", version = "1.0", description = "SpringBoot接口文檔")
)
public class SpringDocConfig { 
  // 無需額外代碼
}

注解使用

常用注解

場景	SpringDoc 注解	示例
控制器描述	@Tag(name="模塊", description="")	@Tag(name="用戶管理", description="用戶CRUD")
接口方法描述	@Operation(summary="", description="")	@Operation(summary="創(chuàng)建用戶", description="需管理員權(quán)限")
參數(shù)描述	@Parameter(description="")	@Parameter(description="用戶ID", required=true)
模型屬性描述	@Schema(description="")	public class User { @Schema(description="用戶名") private String name; }l
解析對象屬性為查詢參數(shù)	@ParameterObject	public BizResponse getUserPage(@ParameterObject UserPageForm form) {}

提示：

@Hidden 可隱藏接口或參數(shù)；
支持 Spring Security 的 @PreAuthorize 注解，自動在文檔中標記權(quán)限需求。

控制層注解使用示例

@RestController
@RequestMapping("/api/users")
@Tag(name = "用戶管理", description = "用戶相關(guān)操作API")
public class UserController{

    @Operation(summary = "獲取用戶信息", description = "通過用戶id獲取用戶信息")
    @Parameters({
        @Parameter(in = ParameterIn.PATH, name = "id", description = "用戶uid", required = true)
    })
    @ApiResponse(responseCode = "404", description = "User not found")
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id){
        // 實現(xiàn)代碼
        return new ResponseEntity(new User(10001,"feng","ADMIN"), HttpStatusCode.valueOf(200));
    }
    
    @Operation(summary = "獲取用戶列表-分頁")
    @GetMapping("/userPage.do")
    public BizResponse getUserPage(@ParameterObject UserPageForm form) {
        return BizResponse.ok(userServer.getUserPage(form));
    }
    
    @Operation(summary = "文件上傳")
    @PostMapping(name = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public BizResponse<FileInfoVo> fileUpload(
            @Parameter(description = "文件",
                    content = @Content(mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
                            schema = @Schema(type = "string", format = "binary")))
            @RequestParam MultipartFile file) {
        FileInfo fileInfo = fileStorageService.of(file).setPath(uploadFilePath).upload();
        return BizResponse.ok(fileInfo);
    }
}

模型注解使用示例

import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.Size;

@data
public clas sUser{

    @Schema(description = "用戶ID", example = "1001")
    private Integer id;

    @Schema(description = "用戶名", example = "john_doe", requiredMode = RequiredMode.REQUIRED)
    @Size(min = 3, max = 20, message = "用戶名長度必須在3到20個字符之間")
    private String username;
    
    @Schema(description = "用戶角色", allowableValues = {"ADMIN", "USER", "GUEST"})
    private String role;

    @Schema(description = "郵箱", example = "john_doe@mail.com")
    @Email
    private String email;
    
    @Schema(description = "最近登錄時間", example = "2025-07-15 12:25:32", type = "string")
    private Date lastLoginTime;
    
    @Schema(description = "出生年月日", example = "2025-07-15", type = "string")
    @JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
    private Date birthDate;
}

文件上傳注解使用示例

文件上傳必須聲明以下配置，否則 SpringDoc 無法識別為文件類型，文件參數(shù)不會顯示為文件上傳控件

@PostMapping 必須配置 consumes = MediaType.MULTIPART_FORM_DATA_VALUE
MultipartFile 參數(shù)必須明確聲明 format = "binary"

單文件上傳

@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
@Operation(summary = "上傳文件")
public ResponseEntity<String> uploadFile(
    @Parameter(
        description = "文件參數(shù)",
        required = true,
        content = @Content( // 關(guān)鍵：嵌套Content注解
            mediaType = MediaType.APPLICATION_OCTET_STREAM_VALUE,
            schema = @Schema(type = "string", format = "binary") // 明確格式
        )
    )
    @RequestParam("file") MultipartFile file) {
    // 業(yè)務(wù)邏輯
}

多文件上傳（數(shù)組形式）

@Parameter(
    description = "多文件上傳",
    content = @Content(
        mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
        array = @ArraySchema( // 聲明數(shù)組類型
            schema = @Schema(type = "string", format = "binary")
        )
    )
)
@RequestParam("files") MultipartFile[] files

混合參數(shù)（文件+表單數(shù)據(jù)）

@RequestBody(
    description = "混合參數(shù)請求",
    content = @Content(
        mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
        encoding = {
            @Encoding(name = "file", contentType = "image/jpeg"), // 指定文件類型
            @Encoding(name = "remark", contentType = "text/plain") // 文本參數(shù)
        }
    )
)
@RequestPart("file") MultipartFile file,
@RequestPart("remark") String remark

分組與擴展功能

分組配置

按模塊隔離接口

@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
        .group("公開接口")
        .pathsToMatch("/api/public/**")
        .build();
}

@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
        .group("管理接口")
        .pathsToMatch("/api/admin/**")
        .addOpenApiMethodFilter(method -> method.isAnnotationPresent(PreAuthorize.class))
        .build();
}

訪問 Swagger UI 右上角切換分組

生產(chǎn)環(huán)境安全建議

通過配置動態(tài)關(guān)閉文檔

springdoc:
  swagger-ui:
    enabled: false   # 生產(chǎn)環(huán)境禁用 UI
  api-docs:
    enabled: false   # 禁用 OpenAPI 端點:cite[1]

從 SpringFox 遷移指南

SpringFox 注解	SpringDoc 替代方案
@Api	@Tag
@ApiOperation	@Operation(summary="", description="")
@ApiModelProperty	@Schema(description="")
@ApiParam	@Parameter
@ApiIgnore	@Hidden

遷移優(yōu)勢：

支持 Spring Boot 3.x 和 JDK 17+；
注解更簡潔，符合 OpenAPI 3 規(guī)范

最佳實踐與常見問題

依賴沖突

排除舊版 Swagger 依賴（如 springfox-swagger2），避免與 SpringDoc 沖突1。
攔截器導(dǎo)致文檔無法訪問

若項目使用 Spring Security，需放行文檔路徑：
```
http.authorizeRequests().antMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll();
```
文檔生成失敗排查

檢查控制器是否被掃描：確保 @RestController 位于 springdoc.packages-to-scan 指定路徑下