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，直接復(fù)制就能用。
一、核心常用注解（必掌握）
1.@Tag
作用：給 Controller / 接口模塊 打標(biāo)簽，用于分組顯示。
@RestController
@RequestMapping("/user")
@Tag(name = "用戶管理模塊", description = "用戶的增刪改查接口")
public class UserController {
}
效果：Swagger UI 左側(cè)會顯示一個分組：用戶管理模塊
2.@Operation
作用：描述單個接口方法，相當(dāng)于接口說明。
@Operation(
summary = "根據(jù)ID查詢用戶",
description = "傳入用戶ID，返回用戶詳細(xì)信息",
tags = {"用戶管理模塊"}
)
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
}
常用屬性：
summary：接口簡短說明description：詳細(xì)描述tags：歸屬分組method：請求方法（一般不用寫，自動識別）hidden：是否隱藏接口
3.@Parameter
作用：描述路徑參數(shù) / 查詢參數(shù)。
@GetMapping("/{id}")
public User getUser(
@Parameter(description = "用戶ID", required = true, example = "1001")
@PathVariable Long id
) {
}
常用屬性：
description：參數(shù)說明required：是否必填example：示例值hidden：隱藏參數(shù)
4.@ApiResponse/@ApiResponses
作用：定義接口響應(yīng)狀態(tài)碼與說明。
@Operation(...)
@ApiResponses({
@ApiResponse(responseCode = "200", description = "查詢成功"),
@ApiResponse(responseCode = "404", description = "用戶不存在"),
@ApiResponse(responseCode = "500", description = "服務(wù)器異常")
})
@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 等）
三、實用增強(qiáng)注解
6.@Hidden
作用：隱藏某個接口、類、字段，不在 Swagger 顯示。
@Hidden
@GetMapping("/internal")
public void internalApi() {
}
7.@Parameters
多個參數(shù)統(tǒng)一包裹（不常用，一般直接每個參數(shù)加 @Parameter）
8.@RequestBody搭配 OpenAPI
SpringDoc 會自動識別 @RequestBody，你只需要給 DTO 加 @Schema 即可。
四、完整示例（可直接復(fù)制）
@RestController
@RequestMapping("/user")
@Tag(name = "用戶管理模塊", description = "用戶相關(guān)接口")
public class UserController {
@Operation(
summary = "根據(jù)ID查詢用戶",
description = "根據(jù)用戶唯一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
（注：文檔部分內(nèi)容由 AI 生成）
到此這篇關(guān)于SpringDoc OpenAPI 3 常用注解使用方法的文章就介紹到這了,更多相關(guān)SpringDoc OpenAPI 3 注解內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！
您可能感興趣的文章:
- Springboot整合Swagger3全注解配置(springdoc-openapi-ui)
- SpringDoc OpenAPI 泛型返回值完美解決方案(最新推薦)
- SpringBoot使用SpringDoc+OpenAPI3.0實現(xiàn)接口文檔自動生成
- springdoc-openapi用戶界面實現(xiàn)將請求設(shè)置為HTTPS
- 從Springfox到SpringDoc OpenAPI的完整遷移指南
- springboot集成springdoc-openapi的案例講解(模擬前端請求)
- SpringBoot3整合SpringDoc OpenAPI生成接口文檔的詳細(xì)過程
- springdoc?openapi使用解決方案
相關(guān)文章
這篇文章主要介紹了Java集合源碼ArrayList的可視化操作過程示例詳解,本文給大家介紹的非常詳細(xì),對大家的學(xué)習(xí)或工作具有一定的參考借鑒價值,需要的朋友參考下吧2025-06-06
詳解Java虛擬機(jī)30個常用知識點(diǎn)之1——類文件結(jié)構(gòu)
這篇文章主要介紹了Java虛擬機(jī)類文件結(jié)構(gòu)，文中通過示例代碼介紹的非常詳細(xì)，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值，需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2019-03-03
maven打包生成的普通jar包,只包含該工程下源碼編譯結(jié)果,不包含依賴內(nèi)容,下面這篇文章主要給大家介紹了關(guān)于maven項目打jar包并包含所有依賴的相關(guān)資料,需要的朋友可以參考下2023-05-05
這篇文章主要介紹了java?oshi如何查看cpu信息，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2022-01-01
java實現(xiàn)隊列數(shù)據(jù)結(jié)構(gòu)代碼詳解
這篇文章主要介紹了java實現(xiàn)隊列數(shù)據(jù)結(jié)構(gòu)代碼詳解，簡單介紹了隊列結(jié)構(gòu)以應(yīng)用場景，涉及詳細(xì)實現(xiàn)代碼，還是比較不錯的，這里分享給大家，需要的朋友可以參考下。2017-11-11
關(guān)于ResponseEntity類和HttpEntity及跨平臺路徑問題
這篇文章主要介紹了關(guān)于ResponseEntity類和HttpEntity及跨平臺路徑問題,具有很好的參考價值,希望對大家有所幫助,如有錯誤或未考慮完全的地方,望不吝賜教2024-07-07
這篇文章主要介紹了JavaAgent原理及實踐,具有很好的參考價值,希望對大家有所幫助,如有錯誤或未考慮完全的地方,望不吝賜教2025-04-04
JAVA發(fā)送http get/post請求，調(diào)用http接口、方法詳解
這篇文章主要介紹了Java發(fā)送http get/post請求調(diào)用接口/方法，文中通過示例代碼介紹的非常詳細(xì)，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值，需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2019-04-04
本文詳細(xì)介紹了Hadoop NameNode高可用機(jī)制的各個方面內(nèi)容，NameNode 的可用性直接決定了 Hadoop 集群的可用性，感興趣的小伙伴可以參考本文章2021-08-08
在日常開發(fā)中,數(shù)據(jù)持久層是幾乎每個項目都會涉及的一個關(guān)鍵組成部分,MyBatis作為一個流行的持久層框架,其提供的接口綁定機(jī)制極大地簡化了數(shù)據(jù)庫操作,本文將通過詳細(xì)的代碼示例和講解,帶你深入理解MyBatis接口綁定的工作原理和實踐方式,需要的朋友可以參考下2024-03-03