Swagger註解的規範用法 提高前後端及測試配合效率

詳解

https://blog.csdn.net/xiaojin21cen/article/details/78654652###

用法

1.@ApiParam結合JAX-RS註解或Sping web.bind註解組合使用

代碼樣例：

    @ApiOperation(value = "測試swagger註解")
    @PostMapping("/testSwagger/{id}")
    public ServiceResponse testSwagger(
            @ApiParam(name = "userInfoReqVO", value = "RequestBody參數", required = true) @RequestBody UserInfoReqVO userInfoReqVO,
            @ApiParam(name = "code", value = "RequestParam參數", required = true) @RequestParam String code,
            @ApiParam(name = "id", value = "PathVariable參數", required = true) @PathVariable Long id){
        return  ServiceResponse.handleSuccess("testSwagger");
    }

swagger-UI效果：

2.源碼註釋表示：@ApiImplicitParam 在非JAX-RS情景下使用（比如servlet這種沒有顯式請求參數的情況），且必須作爲@ApiImplicitParams註解的一個子項

實際上  @ApiImplicitParam 可以單獨使用 ，用法如下

@Api(tags = "示例接口")
@RestController
class ExampleController {

    @ApiOperation(value = "列表查詢", notes = "列表查詢")
    // 這裏的dataType必須和ExampleReqVO的@ApiModel註解的value對應，最好是直接使用類名
    // name必須和要添加說明文檔的參數名稱對應
    @ApiImplicitParam(name = "reqVO", value = "示例請求VO", dataType = "ExampleReqVO", required = true)
    @PostMapping("/list")
    ServerResponse<List<ExampleRepVO>> list(@RequestBody ExampleReqVO reqVO) {
        
    }

}


// 這裏 @ApiModel 註解的value 必須 和@ApiImplicitParam的dataType對應，且默認值就是取的類名，可以不寫，description不是必須
@ApiModel(value="ExampleReqVO",description = "示例請求VO")
public class ExampleReqVO extends BaseReqVO {
    
    // 字段註解必須
    @ApiModelProperty("編碼")
    private String code;

}


// 這裏@ApiModel註解的value默認值就是取的類名，所以可以不寫，description不是必須
@ApiModel(value="ExampleRepVO",description = "示例響應VO")
public class ExampleRepVO extends BaseReqVO {

    // 字段註解必須
    @ApiModelProperty("編碼")
    private String code;

}