Swagger筆記之Swagger注解

@

目錄

• Swagger-注解：
• Controller 控制器
  • @Api
  • @ApiOperation
  • @ApiParam
  • @ApiResponse
  • @ApiResponses
  • @ResponseHeader
  • 火中取栗
• VO 返回對象
  • @ApiModel
  • @ApiModelProperty
  • 火中取栗
• 注意：

相關內容	地址
Swagger官方文檔	https://swagger.io/docs/specification/2-0/basic-structure/
Swagger常用注解	https://blog.csdn.net/weixin_42526326/article/details/119824857
Swagger2常用注解	https://blog.csdn.net/weixin_42526326/article/details/119963866
Swagger3常用注解	https://blog.csdn.net/weixin_42526326/article/details/119965092

Swagger-注解：

作用范圍	API	使用位置
協議集描述	@Api	用於controller類上
對象屬性	@ApiModelProperty	用在出入參數對象的字段上
協議描述	@ApiOperation	用在controller的方法上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里邊
非對象參數集	@ApiImplicitParams	用在controller的方法上
非對象參數描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里邊
校驗綁定的參數	@Valiated	用在controller的方法上
描述返回對象的意義	@ApiModel	用在返回對象類上

api標記，用在類上，說明該類的作用。可以標記一個Controller類做為Swagger文檔資源，使用方式

與Controller注解並列使用。 屬性配置：

Controller 控制器

@Api

tags 一定要寫，不然swagger掃描顯示的是類名

屬性名稱	備注
value	url的路徑值
tags	如果設置這個值、value的值會被覆蓋
description	對api資源的描述
basePath	基本路徑可以不配置
position	如果配置多個Api 想改變顯示的順序位置
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高級特性認證時配置
hidden	配置為true 將在文檔中隱藏

@ApiOperation

ApiOperation標記，用在方法上，說明方法的作用，每一個url資源的定義,使用方式：

@ApiOperation("獲取用戶信息")

與Controller中的方法並列使用，屬性配置：

屬性名稱	備注
value	url的路徑值
tags	如果設置這個值、value的值會被覆蓋
description	對api資源的描述
basePath	基本路徑可以不配置
position	如果配置多個Api 想改變顯示的順序位置
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高級特性認證時配置
hidden	配置為true將在文檔中隱藏
response	返回的對象
responseContainer	這些對象是有效的 "List", "Set" or "Map".，其他無效
httpMethod	"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code	http的狀態碼 默認 200
extensions	擴展屬性

@ApiParam

ApiParam標記，請求屬性，使用方式：

public TableDataInfo list(@ApiParam(value = "查詢用戶列表", required = true)User user)

與Controller中的方法並列使用，屬性配置：

屬性名稱	備注
name	屬性名稱
value	屬性值
defaultValue	默認屬性值
allowableValues	可以不配置
required	是否屬性必填
access	不過多描述
allowMultiple	默認為false
hidden	隱藏該屬性
example	舉例子

@ApiResponse

ApiResponse標記，響應配置，使用方式：

@ApiResponse(code = 400, message = "查詢用戶失敗")

與Controller中的方法並列使用，屬性配置：

屬性名稱	備注
code	http的狀態碼
message	描述
response	默認響應類 Void
reference	參考ApiOperation中配置
responseHeaders	參考 ResponseHeader 屬性配置說明
responseContainer	參考ApiOperation中配置

@ApiResponses

ApiResponses標記，響應集配置，使用方式:

@ApiResponses({ @ApiResponse(code = 400, message = "無效的用戶") })

與Controller中的方法並列使用，屬性配置：

屬性名稱	備注
value	多個ApiResponse配置

@ResponseHeader

ResponseHeader標記，響應頭設置，使用方法

@ResponseHeader(name="head",description="響應頭設計")

與Controller中的方法並列使用，屬性配置：

屬性名稱	備注
name	響應頭名稱
description	描述
response	默認響應類 void
responseContainer	參考ApiOperation中配置

火中取栗

@RestController
@RequestMapping("/msg/im")
@Api(tags = "消息-IM")
public class IMController {

    @ApiOperation("生成用戶簽名")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId", value = "用戶ID", required = true, dataType = "String")
    })
    @GetMapping("/{userId}")
    public R<String> test(@PathVariable("userId") @ApiParam(value = "用戶ID", required = true) String userId) {
        return R.ok(IMTencentUtil.genUserSig(userId));
    }
}

VO 返回對象

其中@Null、@NotNull。。等與@Valiated 配合使用

限制	說明
@Null	限制只能為null
@NotNull	限制必須不為null
@AssertFalse	限制必須為false
@AssertTrue	限制必須為true
@DecimalMax(value)	限制必須為一個不大於指定值的數字
@DecimalMin(value)	限制必須為一個不小於指定值的數字
@Digits(integer,fraction)	限制必須為一個小數，且整數部分的位數不能超過integer，小數部分的位數不能超過fraction
@Future	限制必須是一個將來的日期
@Max(value)	限制必須為一個不大於指定值的數字
@Min(value)	限制必須為一個不小於指定值的數字
@Past	限制必須是一個過去的日期
@Pattern(value)	限制必須符合指定的正則表達式
@Size(max,min)	限制字符長度必須在min到max之間
@Past	驗證注解的元素值（日期類型）比當前時間早
@NotEmpty	驗證注解的元素值不為null且不為空（字符串長度不為0、集合大小不為0）
@NotBlank	驗證注解的元素值不為空（不為null、去除首位空格后長度為0），不同於@NotEmpty，@NotBlank只應用於字符串且在比較時會去除字符串的空格
@Email	驗證注解的元素值是Email，也可以通過正則表達式和flag指定自定義的email格式

@ApiModel

用在返回對象類上

屬性名稱	備注
value	默認 為模型提供一個替代名稱
description	描述
referencey	指定對相應類型定義的引用，覆蓋指定的任何其他元數據

@ApiModelProperty

用在返回對象的屬性上

屬性名稱	備注
value	默認 字段說明
name	重寫屬性名字
dataType	重寫屬性類型
required	是否必填
example	舉例說明
hidden	配置為true將在文檔中隱藏

火中取栗

@ApiModel("testVo")
public class MsgPageVO
{
    /** 消息ID */
    @ApiModelProperty("消息ID")
    private Long msgId;
}

注意：

@Api(tags = "")寫，不然swagger掃描顯示的是類名

持續更新中。。。。