swagger注釋API詳細說明

轉載：https://blog.csdn.net/xupeng874395012/article/details/68946676

鏈接：https://www.jianshu.com/p/12f4394462d5

API詳細說明

注釋匯總

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

 

作用在 controller 層：

 /**  Controller 層
     * 取消發布
     */
    @PostMapping("/exitpub")
    @ApiOperation(value = "圖書取消發布",produces = "application/json", consumes="application/json")
    @RequiresPermissions("cms:bookresource:publish")
    @ApiImplicitParam(name="ids",allowMultiple = true,value = "id數組",required=true,paramType = "body",dataType="Long")
    public R unpublish(@PathVariable("ids") String[] ids){

 作用在實體層 entity

 @ApiModelProperty("編輯")
    @TableField(exist = false)
    private List<EditorEntity> editorList = new ArrayList<>();

 

@ApiImplicitParam

屬性	取值	作用
paramType		查詢參數類型
	path	以地址的形式提交數據
	query	直接跟參數完成自動映射賦值
	body	以流的形式提交 僅支持POST
	header	參數在request headers 里邊提交
	form	以form表單的形式提交 僅支持POST
dataType		參數的數據類型 只作為標志說明，並沒有實際驗證
	Long
	String
name		接收參數名
value		接收參數的意義描述
required		參數是否必填
	true	必填
	false	非必填
defaultValue		默認值

 

  @ApiImplicitParam(name = "id",value = "資源id",required=false,paramType = "path",dataType="Long")

 

 paramType 示例詳解

path

@RequestMapping(value = "/findById1/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)

 @PathVariable(name = "id") Long id

 

body

 @ApiImplicitParams({ @ApiImplicitParam(paramType = "body", dataType = "MessageParam", name = "param", value = "信息參數", required = true) })
  @RequestMapping(value = "/findById3", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE)

  @RequestBody MessageParam param

  提交的參數是這個對象的一個json，然后會自動解析到對應的字段上去，也可以通過流的形式接收當前的請求數據，但是這個和上面的接收方式僅能使用一個（用@RequestBody之后流就會關閉了）

 

header

 @ApiImplicitParams({ @ApiImplicitParam(paramType = "header", dataType = "Long", name = "id", value = "信息id", required = true) }) 

   String idstr = request.getHeader("id");
        if (StringUtils.isNumeric(idstr)) {
            id = Long.parseLong(idstr);
        }

 

Form

@ApiImplicitParams({ @ApiImplicitParam(paramType = "form", dataType = "Long", name = "id", value = "信息id", required = true) })
 @RequestMapping(value = "/findById5", method = RequestMethod.POST, produces = MediaType.APPLICATIO

 

 常用 swagger 注解

常用到的注解有：

• Api
• ApiModel
• ApiModelProperty
• ApiOperation
• ApiParam
• ApiResponse
• ApiResponses
• ResponseHeader

1. api標記

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

@Api(value = "/user", description = "Operations about user")

與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 將在文檔中隱藏

在SpringMvc中的配置如下：

@Controller @RequestMapping(value = "/api/pet", produces = {APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE}) @Api(value = "/pet", description = "Operations about pets") public class PetController { } 

2. ApiOperation標記

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

@ApiOperation( value = "Find purchase order by ID", notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions", response = Order, tags = {"Pet Store"}) 

與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	擴展屬性

在SpringMvc中的配置如下：

@RequestMapping(value = "/order/{orderId}", method = GET) @ApiOperation( value = "Find purchase order by ID", notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions", response = Order.class, tags = { "Pet Store" }) public ResponseEntity<Order> getOrderById(@PathVariable("orderId") String orderId) throws NotFoundException { Order order = storeData.get(Long.valueOf(orderId)); if (null != order) { return ok(order); } else { throw new NotFoundException(404, "Order not found"); } } 

3. ApiParam標記

ApiParam請求屬性,使用方式：

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true) User user) 

與Controller中的方法並列使用。

屬性配置：

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

在SpringMvc中的配置如下：

 public ResponseEntity<Order> getOrderById( @ApiParam(value = "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true) @PathVariable("orderId") String orderId) 

4. ApiResponse

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

@ApiResponse(code = 400, message = "Invalid user supplied") 

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

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

在SpringMvc中的配置如下：

 @RequestMapping(value = "/order", method = POST) @ApiOperation(value = "Place an order for a pet", response = Order.class) @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") }) public ResponseEntity<String> placeOrder( @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) { storeData.add(order); return ok(""); } 

5. ApiResponses

ApiResponses：響應集配置，使用方式：

 @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") }) 

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

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

在SpringMvc中的配置如下：

 @RequestMapping(value = "/order", method = POST) @ApiOperation(value = "Place an order for a pet", response = Order.class) @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") }) public ResponseEntity<String> placeOrder( @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) { storeData.add(order); return ok(""); } 

6. ResponseHeader

響應頭設置，使用方法

@ResponseHeader(name="head1",description="response head conf") 

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

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

在SpringMvc中的配置如下：

@ApiModel(description = "群組") 

7. 其他

• @ApiImplicitParams：用在方法上包含一組參數說明；
• @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數的各個方面@ApiResponses：用於表示一組響應；
  • paramType：參數放在哪個地方
  • name：參數代表的含義
  • value：參數名稱
  • dataType： 參數類型，有String/int，無用
  • required ： 是否必要
  • defaultValue：參數的默認值
• @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息；@ApiModel：描述一個Model的信息（這種一般用在post創建的時候，使用@RequestBody這樣的場景，請求參數無法使用@ApiImplicitParam注解進行描述的時候；
  • code： 響應碼(int型)，可自定義
  • message：狀態碼對應的響應信息
• @ApiModelProperty：描述一個model的屬性。