swagger註解

API詳細說明

註釋彙總

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

@RequestMapping此註解的推薦配置
value
method
produces

示例：

@ApiOperation("信息軟刪除")
    @ApiResponses({ @ApiResponse(code = CommonStatus.OK, message = "操做成功"),
            @ApiResponse(code = CommonStatus.EXCEPTION, message = "服務器內部異常"),
            @ApiResponse(code = CommonStatus.FORBIDDEN, message = "權限不足") })
    @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "Long", name = "id", value = "信息id", required = true) })
    @RequestMapping(value = "/remove.json", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public RestfulProtocol remove(Long id) {

• 1
• 2
• 3
• 4
• 5
• 6
• 7

• 1
• 2
• 3
• 4
• 5
• 6
• 7

@ApiModelProperty(value = "標題")
    private String  title;

• 1
• 2

• 1
• 2

@ApiImplicitParam

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

paramType 示例詳解

path

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

 @PathVariable(name = "id") Long id

• 1
• 2
• 3

• 1
• 2
• 3

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以後流就會關閉了）

• 1
• 2
• 3
• 4
• 5
• 6
• 7

• 1
• 2
• 3
• 4
• 5
• 6
• 7

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);
        }

• 1
• 2
• 3
• 4
• 5
• 6

• 1
• 2
• 3
• 4
• 5
• 6

Form

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

• 1
• 2

• 1
• 2