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的屬性。