SpringDoc OpenAPI 3 常用注解使用方法
更新時間：2026年04月07日 09:13:48 作者：伯恩bourne
本文介紹了SpringDoc/OpenAPI3在SpringBoot4+項目中的常用注解,包括@Tag、@Operation、@Parameter、@ApiResponse等核心注解,以及@Schema、@Hidden、@Parameters等實用注解的使用方法,并提供了一個完整示例,感興趣的朋友跟隨小編一起看看吧
SpringDoc / OpenAPI 3 最常用注解，適配 Spring Boot 4 + springdoc-openapi 3.x，直接復制就能用。
一、核心常用注解（必掌握）
1.@Tag
作用：給 Controller / 接口模塊 打標簽，用于分組顯示。
@RestController
@RequestMapping("/user")
@Tag(name = "用戶管理模塊", description = "用戶的增刪改查接口")
public class UserController {
}
效果：Swagger UI 左側會顯示一個分組：用戶管理模塊
2.@Operation
作用：描述單個接口方法，相當于接口說明。
@Operation(
summary = "根據ID查詢用戶",
description = "傳入用戶ID，返回用戶詳細信息",
tags = {"用戶管理模塊"}
)
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
}
常用屬性：
summary：接口簡短說明description：詳細描述tags：歸屬分組method：請求方法（一般不用寫，自動識別）hidden：是否隱藏接口
3.@Parameter
作用：描述路徑參數 / 查詢參數。
@GetMapping("/{id}")
public User getUser(
@Parameter(description = "用戶ID", required = true, example = "1001")
@PathVariable Long id
) {
}
常用屬性：
description：參數說明required：是否必填example：示例值hidden：隱藏參數
4.@ApiResponse/@ApiResponses
作用：定義接口響應狀態(tài)碼與說明。
@Operation(...)
@ApiResponses({
@ApiResponse(responseCode = "200", description = "查詢成功"),
@ApiResponse(responseCode = "404", description = "用戶不存在"),
@ApiResponse(responseCode = "500", description = "服務器異常")
})
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
}
二、實體類常用注解
5.@Schema
作用：描述DTO、實體類、字段的含義、示例、約束。
用在類上
@Schema(description = "用戶信息實體")
public class User {
}
用在字段上
@Schema(description = "用戶ID", example = "1001") private Long id; @Schema(description = "用戶名", requiredMode = Schema.RequiredMode.REQUIRED) private String username;
常用屬性：
description：字段說明example：示例requiredMode：是否必填hidden：隱藏字段minLength / maxLength：長度限制format：格式（password、email 等）
三、實用增強注解
6.@Hidden
作用：隱藏某個接口、類、字段，不在 Swagger 顯示。
@Hidden
@GetMapping("/internal")
public void internalApi() {
}
7.@Parameters
多個參數統一包裹（不常用，一般直接每個參數加 @Parameter）
8.@RequestBody搭配 OpenAPI
SpringDoc 會自動識別 @RequestBody，你只需要給 DTO 加 @Schema 即可。
四、完整示例（可直接復制）
@RestController
@RequestMapping("/user")
@Tag(name = "用戶管理模塊", description = "用戶相關接口")
public class UserController {
@Operation(
summary = "根據ID查詢用戶",
description = "根據用戶唯一ID查詢用戶詳情"
)
@ApiResponses({
@ApiResponse(responseCode = "200", description = "成功"),
@ApiResponse(responseCode = "404", description = "用戶不存在")
})
@GetMapping("/{id}")
public User getUser(
@Parameter(description = "用戶ID", required = true, example = "1001")
@PathVariable Long id
) {
return new User();
}
}@Schema(description = "用戶信息")
public class User {
@Schema(description = "用戶ID", example = "1001")
private Long id;
@Schema(description = "用戶名", requiredMode = Schema.RequiredMode.REQUIRED)
private String username;
}五、訪問地址
啟動后訪問：
http://localhost:端口/swagger-ui.html
（注：文檔部分內容由 AI 生成）
到此這篇關于SpringDoc OpenAPI 3 常用注解使用方法的文章就介紹到這了,更多相關SpringDoc OpenAPI 3 注解內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！
您可能感興趣的文章:
相關文章
這篇文章主要介紹了Java集合源碼ArrayList的可視化操作過程示例詳解,本文給大家介紹的非常詳細,對大家的學習或工作具有一定的參考借鑒價值,需要的朋友參考下吧2025-06-06
這篇文章主要介紹了Java虛擬機類文件結構，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧2019-03-03
maven打包生成的普通jar包,只包含該工程下源碼編譯結果,不包含依賴內容,下面這篇文章主要給大家介紹了關于maven項目打jar包并包含所有依賴的相關資料,需要的朋友可以參考下2023-05-05
這篇文章主要介紹了java?oshi如何查看cpu信息，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2022-01-01
這篇文章主要介紹了java實現隊列數據結構代碼詳解，簡單介紹了隊列結構以應用場景，涉及詳細實現代碼，還是比較不錯的，這里分享給大家，需要的朋友可以參考下。2017-11-11
關于ResponseEntity類和HttpEntity及跨平臺路徑問題
這篇文章主要介紹了關于ResponseEntity類和HttpEntity及跨平臺路徑問題,具有很好的參考價值,希望對大家有所幫助,如有錯誤或未考慮完全的地方,望不吝賜教2024-07-07
這篇文章主要介紹了JavaAgent原理及實踐,具有很好的參考價值,希望對大家有所幫助,如有錯誤或未考慮完全的地方,望不吝賜教2025-04-04
JAVA發(fā)送http get/post請求，調用http接口、方法詳解
這篇文章主要介紹了Java發(fā)送http get/post請求調用接口/方法，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧2019-04-04
本文詳細介紹了Hadoop NameNode高可用機制的各個方面內容，NameNode 的可用性直接決定了 Hadoop 集群的可用性，感興趣的小伙伴可以參考本文章2021-08-08
在日常開發(fā)中,數據持久層是幾乎每個項目都會涉及的一個關鍵組成部分,MyBatis作為一個流行的持久層框架,其提供的接口綁定機制極大地簡化了數據庫操作,本文將通過詳細的代碼示例和講解,帶你深入理解MyBatis接口綁定的工作原理和實踐方式,需要的朋友可以參考下2024-03-03