千峰商城-springboot项目搭建-08-swagger常用注解

swagger提供了一套注解，可以对每个接口进行详细说明。

1.@Api

类注解，在控制器类添加此注解可以对控制器类进行功能说明。

示例：在api子工程的UserController中增加api注释：

@Controller
@ResponseBody//异步请求，返回js数据
@RequestMapping("/user")
@Api(value = "提供用户的登录和注册接口",tags = "用户管理")
public class UserController {//接收和响应

    @Resource
    private UserService userService;

    @RequestMapping(value = "/login",method = RequestMethod.GET)
    public ResultVO login(@RequestParam("username") String name,@RequestParam(value = "password",defaultValue = "111111") String pwd){
        return userService.checkLogin(name,pwd);
    }

    @RequestMapping(value = "/regist",method = RequestMethod.POST)
    public ResultVO regist(User user){
        System.out.println("regist");
        return new ResultVO(10000,"SUCCESS",null);
    }
}

 启动项目，查看效果：

http://localhost:8080/swagger-ui.html

 GoodsController.java:

@Controller
@RequestMapping("/goods")
@Api(value = "提供商品添加，修改，删除及查询的相关接口",tags = "商品管理")
public class GoodsController {

    @RequestMapping(value = "/add",method = RequestMethod.POST)
    public ResultVO addGoods(){
        return null;
    }

    @RequestMapping(value = "/delete",method = RequestMethod.DELETE)
    public ResultVO deleteGoods(int goodsId){
        return null;
    }

    @RequestMapping(value = "/update",method = RequestMethod.PUT)
    public ResultVO updateGoods(){
        return null;
    }


    @RequestMapping(value = "/list",method = RequestMethod.GET)
    public ResultVO listGoods(){
        return null;
    }
}

2.@ApiOperation,@ApiImplicitParams,@ApiImplicitParam:

@ApiOperation：说明接口方法的作用。
@ApiImplicitParams,@ApiImplicitParam:说明接口方法的参数。

userController.java:

@Controller
@ResponseBody//异步请求，返回js数据
@RequestMapping("/user")
@Api(value = "提供用户的登录和注册接口",tags = "用户管理")
public class UserController {//接收和响应

    @Resource
    private UserService userService;

    @ApiOperation("用户登录接口")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "string",name = "username",value = "用户登录账号",required = true),
            @ApiImplicitParam(dataType = "string",name = "password",value = "用户登录密码",required = false,defaultValue = "111111")
    })
    @RequestMapping(value = "/login",method = RequestMethod.GET)
    public ResultVO login(@RequestParam("username") String name,@RequestParam(value = "password",defaultValue = "111111") String pwd){
        return userService.checkLogin(name,pwd);
    }

　　@ApiOperation("用户注册接口")
　　@ApiImplicitParam(name = "用户信息",required = true)
　　@RequestMapping(value = "/regist",method = RequestMethod.POST)
　　public ResultVO regist(User user){
 　　System.out.println("regist");
 　　return new ResultVO(10000,"SUCCESS",null);
　　}

}

在common子工程的pom.xml中添加swagger依赖：

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

 3.@ApiModel，@ApiModelProperty：

当接口参数和返回值为对象类型时，在实体类中添加注解说明。

 ResultVO.java:

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "resultVO对象",description = "封装接口返回给前端的数据")
public class ResultVO {

    @ApiModelProperty(value = "响应状态码",dataType = "int")
private int code;//响应给前端的状态码
 @ApiModelProperty("响应提示信息")
private String msg;//传递给前端的提示信息
 @ApiModelProperty("响应数据")
private Object data;//响应给前端的数据
}

 在beans子工程的pom.xml中添加依赖：

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

 User.java:

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "User对象",description = "买家信息")
public class User {

    @ApiModelProperty(dataType = "int",required = false)
    private int userId;
    @ApiModelProperty(dataType = "String",required = true,value = "用户注册账号")
    private String userName;
    @ApiModelProperty(dataType = "String",required = true,value = "用户注册密码")
    private String userRealname;
    @ApiModelProperty(dataType = "String",required = true,value = "用户真实姓名")
    private String UserImg;
    @ApiModelProperty(dataType = "String",required = true,value = "用户头像url")
    private String userPwd;
}

运行测试：http://localhost:8080/swagger-ui.html

 点击Try it out ：

4. @ApiIgnore：接口方法注解

添加了此注解的接口不会添加到生成的接口文档中

5.swagger-ui插件

在子项目api的pom.xml中导入插件的依赖：

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

重新运行项目。

访问测试：http://localhost:8080/doc.html

 

调试一下数据：

不填写用户名，自己提交时，提示：username不能为空。

 填写(不存在的)用户名 zhang，提交后提示：用户名不存在。

 填写用户名 li，但不填写正确密码，提交后提示：密码错误。

 填写用户名 li和正确密码1234，提交后提示：登录成功，并显示用户信息。