基于 swagger2 的一些基本操作
目录
1. Swagger 简介
前后端分离开发,后端需要编写接口说明文档,耗费时间,swagger 是一个用于`生成服务器接口的规范性文档,并且能够对接口进行测试的工具
2. 作用
- 生成服务器接口的规范性文档
- 对接口进行测试
3. 整合
-
在 api 子工程添加依赖 (Swager2\Swagger UI)
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
-
在 api 子工程创建 swagger 的配置(Java配置方式)
- 新建 config 包,SwaggerConfig类
@Configuration @EnableSwagger2 //启动Swagger2 public class SwaggerConfig { /*swagger 帮助我们生成帮助文档 * 1.配置生成的文档信息 * 2.配置生成的规则 * Docket,封装接口文档信息 * */ public Docket getDocket() { //DocumentationType.SWAGGER_2 :指定文档风格 /* * 如何获取一个接口、抽象类对象 * 1.new 接口,需要在构造器后的{}实现接口中的所有抽象方法 * 2.new 子类/实现类 * 3.工厂模式 * */ ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder(); //创建封面信息对象 apiInfoBuilder.title("《锋迷商城》接口说明") .description("此接口文档实现了.....") .version("v 2.0.1") .contact(new Contact("Mr.Suho", "www.cwaits.xyz", "cwaits@163.com")); ApiInfo apiInfo = apiInfoBuilder.build(); Docket docket = new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo)//指定生成的文档封面信息:文档标题,版本。作者 .select() .apis(RequestHandlerSelectors.basePackage("com.sh.controller")) .paths(PathSelectors.regex("/user/")) .build(); return docket; } }
-
测试
- 启动 SpringBoot 应用,访问:http://localhost:8080/swagger-ui.html
4.Swagger 注解说明
swagger 提供了一套注解,可以对每个接口进行详细说明
-
@api(类注解),在控制器类添加此注解,可以对控制器进行说明
@Api(value = "实现用户登录,注册功能",tags = "用户管理")
-
@ApiImpliciParams 和 @ApiImpliciParam (方法注解),说明接口方法的参数
@ApiImplicitParams({ @ApiImplicitParam(dataType ="String",name = "username",value = "用户登录账号",required = true), @ApiImplicitParam(dataType ="String",name = "pwd",value = "用户登录密码",required = false), }) @RequestMapping(value = "/login",method = RequestMethod.GET) public ResultVo login(String name, String pwd){ return userService.checkLogin(name,pwd); }
-
@ApiOperation(方法注解),说明接口方法的作用
@ApiOperation("用户登录接口") @RequestMapping(value = "/login",method = RequestMethod.GET) public ResultVo login(String name, String pwd){ return userService.checkLogin(name,pwd); }
-
@ApiModel 和 @ApiModelProperty,当接口参数和返回值为对象类型时,在实体类中添加注解说明
@ApiModel(value = "ResultVO对象",description = "封装接口返回给前端的数据") public class ResultVo { //响应给前端的状态码 @ApiModelProperty(value = "响应状态码",dataType = "int") private Integer code; //响应给前端的提示信息 @ApiModelProperty("响应提示信息") private String msg; //响应给前端的数据 @ApiModelProperty("响应数据") private Object data; }
-
@ApiIgnore,接口方法注解,添加此注解的方法将不会生成到接口文档中
@ApiIgnore @RequestMapping(value = "/login",method = RequestMethod.GET) public ResultVo login(String name, String pwd){ return userService.checkLogin(name,pwd); }
5. Swagger-ui 插件
-
导入插件依赖
<!--swagger-ui 插件--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.6</version> </dependency>
-
文档访问:
http://ip:port/doc.html
- http://localhost:8080/doc.html