【java】swagger中api接口传多个参数 @ApiImplicitParam和@ApiImplicitParams

╰半夏微凉° 2024-03-26 12:27 48阅读 0赞

#### 目录 ####

*  1、@ApiImplicitParam
 *  2、@ApiImplicitParams
 *  3. Spring Boot项目中集成Swagger knife4j并自定义访问路径
 *   *  swagger常用注解使用说明

## 1、@ApiImplicitParam ##

作用在方法上，用于设置单个请求参数，用法示例：

@PutMapping("/update")
    @ApiOperation(value = "更新用户信息", notes = "根据用户登录token更新客户端提交的用户资料")
    public Object update() {
        
        Map<String,Object> map = new HashMap<>();
        map.put("list", null);
        return map;
    }

## 2、@ApiImplicitParams ##

作用在方法上，用于包含多个 @ApiImplicitParam，用法示例：

@PostMapping("/register")
    @ApiOperation(value = "用户注册", notes = "APP用户注册")
    @ApiImplicitParams(value = {
        
            @ApiImplicitParam(name = "mobile", value = "手机号码", dataType = "string", paramType = "query", example = "13802780104", required = true),
            @ApiImplicitParam(name = "user_name", value = "登录账号", dataType = "string", paramType = "query", example = "lihailin9073", required = true),
            @ApiImplicitParam(name = "password", value = "登录密码", dataType = "string", paramType = "query", example = "123456", required = true),
            @ApiImplicitParam(name = "validate_code", value = "注册验证码", dataType = "string", paramType = "query", example = "3679", required = true)
    })
    public Object create() {
        
        Map<String,Object> map = new HashMap<>();
        map.put("list", null);
        return map;
    }

各个参数说明：

1.  name ：参数名。
2.  value ： 参数的具体意义，作用。
3.  required ： 参数是否必填。
4.  dataType ：参数的数据类型。
5.  paramType ：查询参数类型，这里有几种形式：
    
    path 以地址的形式提交数据  
    query 直接跟参数完成自动映射赋值  
    body 以流的形式提交 仅支持POST  
    header 参数在request headers 里边提交  
    form 以form表单的形式提交 仅支持POST

当发POST请求的时候，当时接受的整个参数，不论用body还是query，后台都会报Body Missing错误；
    这个参数和SpringMvc中的@RequestBody冲突，去掉paramType对接口测试并没有影响。

**注：** @RequestBody不能用@ApiImplicitParam注解，没用。得用@ApiParam，例如： @RequestBody @ApiParam(name = “”,value = “”) User user，并且@ApiModel(value=“/”)，这样子出现斜杠也是不行的有问题，@ApiModel中不能出现斜杠，这应该是BUG。

## 3. Spring Boot项目中集成Swagger knife4j并自定义访问路径 ##

原文链接：[https://blog.csdn.net/QIU176161650/article/details/109855061][https_blog.csdn.net_QIU176161650_article_details_109855061]

### swagger常用注解使用说明 ###

@Api：用在请求的类上，表示对类的说明
        tags="说明该类的作用，可以在UI界面上看到的注解"
        value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
     
    @ApiOperation：用在请求的方法上，说明方法的用途、作用
        value="说明方法的用途、作用"
        notes="方法的备注说明"
     
    @ApiImplicitParams：用在请求的方法上，表示一组参数说明
        @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
            name：参数名
            value：参数的汉字说明、解释
            required：参数是否必须传
            paramType：参数放在哪个地方
                · header --> 请求参数的获取：@RequestHeader
                · query --> 请求参数的获取：@RequestParam
                · path（用于restful接口）--> 请求参数的获取：@PathVariable
                · body（不常用）
                · form（不常用）    
            dataType：参数类型，默认String，其它值dataType="Integer"       
            defaultValue：参数的默认值
     
    @ApiResponses：用在请求的方法上，表示一组响应
        @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
            code：数字，例如400
            message：信息，例如"请求参数没填好"
            response：抛出异常的类
     
    @ApiModel：用于响应类上，表示一个返回响应数据的信息
                （这种一般用在post创建的时候，使用@RequestBody这样的场景，
                请求参数无法使用@ApiImplicitParam注解进行描述的时候）
        @ApiModelProperty：用在属性上，描述响应类的属性

[https_blog.csdn.net_QIU176161650_article_details_109855061]: https://blog.csdn.net/QIU176161650/article/details/109855061