swagger2 注解整体说明

悠悠 2021-11-10 10:36 524阅读 0赞

## swagger2 注解整体说明 ##

@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：用在属性上，描述响应类的属性

## 1. @Api：用在请求的类上，说明该类的作用 ##

@Api：用在请求的类上，说明该类的作用
        tags="说明该类的作用"
        value="该参数没什么意义，所以不需要配置"

示例  
`@Api(tags="APP用户注册Controller")`

--------------------

## 2. @ApiOperation：用在请求的方法上，说明方法的作用 ##

@ApiOperation："用在请求的方法上，说明方法的作用"
        value="说明方法的作用"
        notes="方法的备注说明"

示例  
`@ApiOperation(value="用户注册",notes="手机号、密码都是必输项，年龄随边填，但必须是数字")`

--------------------

## 3. @ApiImplicitParams：用在请求的方法上，包含一组参数说明 ##

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
        @ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息       
            name：参数名
            value：参数的汉字说明、解释
            required：参数是否必须传
            paramType：参数放在哪个地方
                · header --> 请求参数的获取：@RequestHeader
                · query --> 请求参数的获取：@RequestParam
                · path（用于restful接口）--> 请求参数的获取：@PathVariable
                · body（不常用）
                · form（不常用）    
            dataType：参数类型，默认String，其它值dataType="Integer"       
            defaultValue：参数的默认值

示例

@ApiImplicitParams({
        @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
        @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
        @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
    })

--------------------

## 4、@ApiModelProperty：表示一个返回响应参数字段的信息 ##

@ApiModelProperty注解的模型类的属性上
        参数：value 响应的参数说明
    示例：
    @ApiModelProperty(value = "姓名")
        private String username;

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4NTU1NDkw_size_16_color_FFFFFF_t_70][]

## 5、@ApiResponses：表示响应结果上，带上注释 ##

写在接口方法的上面，和@ApiModelProperty配套使用
    @ApiResponses({
                @ApiResponse(code = 200,message = "OK",response = User.class),
        })

![20200402163410642.png][]

## 6、代码示例 ##

package com.xiaomin.page.controller;
    
    
    import com.baomidou.mybatisplus.core.metadata.IPage;
    import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
    import com.xiaomin.page.pojo.User;
    import com.xiaomin.page.service.UserService;
    import com.xiaomin.page.utils.ResultUtil;
    import com.xiaomin.page.utils.ResultVo;
    import io.swagger.annotations.*;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RequestMapping;
    
    import org.springframework.stereotype.Controller;
    import org.springframework.web.bind.annotation.ResponseBody;
    
    import java.util.List;
    
    /**
     * <p>
     *  前端控制器
     * </p>
     *
     * @author wangxm
     * @since 2020-03-18
     */
    @Api(tags = "用户模块")
    @Controller
    @RequestMapping("/user")
    public class UserController {
    
        @Autowired
        private UserService userService;
    
        /**
         * 分页使用
         * @return
         */
        @GetMapping("/page")
        @ResponseBody
        @ApiOperation(value="用户信息分页")
        @ApiImplicitParams({
                @ApiImplicitParam(name="current",value="当前页码",required=true,paramType="query",defaultValue = "1"),
                @ApiImplicitParam(name="size",value="每页显示多少条信息",required=true,paramType="query",defaultValue = "10"),
        })
        @ApiResponses({
                @ApiResponse(code = 200,message = "OK",response = User.class),
        })
        public ResultVo<User> page(long current,long size){
            Page<User> userPage = new Page<>(current, size);
            userPage.setDesc("id");
            IPage<User> page = userService.page(userPage);
            System.out.println("当前页码："+page.getCurrent());
            System.out.println("每页显示数量："+page.getSize());
            System.out.println("总页数："+page.getPages());
            System.out.println("总记录数："+page.getTotal());
            return ResultUtil.success(page);
        }
    }

截图：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4NTU1NDkw_size_16_color_FFFFFF_t_70 1][]

详细的注解说明请移步：[https://blog.csdn.net/xiaojin21cen/article/details/78654652][https_blog.csdn.net_xiaojin21cen_article_details_78654652]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4NTU1NDkw_size_16_color_FFFFFF_t_70]: /images/20211109/a8e40deeb06c4b598fe244560f35da83.png
[20200402163410642.png]: /images/20211109/b9529dc8b04a48f5aa0049fda36ec9a7.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4NTU1NDkw_size_16_color_FFFFFF_t_70 1]: /images/20211109/690e836107bb46e2a24a2bd4d9b501a0.png
[https_blog.csdn.net_xiaojin21cen_article_details_78654652]: https://blog.csdn.net/xiaojin21cen/article/details/78654652