千峰商城-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,提交后提示:登录成功,并显示用户信息。
分类:
千峰商城项目
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· PowerShell开发游戏 · 打蜜蜂
· 在鹅厂做java开发是什么体验
· 百万级群聊的设计实践
· WPF到Web的无缝过渡:英雄联盟客户端的OpenSilver迁移实战
· 永远不要相信用户的输入:从 SQL 注入攻防看输入验证的重要性