Swagger注解的规范用法提高前后端及测试配合效率

最新推荐文章于 2023-12-27 20:10:35 发布

原创最新推荐文章于 2023-12-27 20:10:35 发布 · 654 阅读

0 ·

CC 4.0 BY-SA版权

后端同时被 2 个专栏收录

27 篇文章

订阅专栏

JAVA

18 篇文章

订阅专栏

本文详述了Swagger注解的规范用法，包括如何结合JAX-RS和Spring Web Bind注解使用@ApiParam，以及在非JAX-RS场景下如何运用@ApiImplicitParam以提高前后端及测试的协同效率。通过示例代码和Swagger-UI展示，帮助开发者更好地理解和应用这些注解。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

详解

https://blog.youkuaiyun.com/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;

}