1. 什么是Swagger
现在测试都提倡自动化测试,那我们作为后台的开发人员,也得进步下啊,以前用postman来测试后台接口,那个麻烦啊,一个字母输错就导致测试失败,现在swagger的出现可谓是拯救了这些开发人员,便捷之处真的不是一点两点。下面我们看下如何在微服务中将springboot与swagger来结合吧。
简单说下,它的出现就是为了方便进行测试后台的restful形式的接口,实现动态的更新,当我们在后台的接口修改了后,swagger可以实现自动的更新,而不需要认为的维护这个接口进行测试。
2. 注解说明
@Api():用于Controller类;表示标识这个类是swagger的资源
@ApiOperation():用于Controller方法;表示一个http请求的操作
@ApiParam():用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等)
@ApiModel():用于domain、DTO、VO等类,表示对类进行说明,用于参数用实体类接收
@ApiModelProperty():用于domain、DTO、VO等方法,字段;表示对model属性的说明或者数据操作更改
@ApiIgnore():用于类,方法,方法参数 表示这个方法或者类被忽略
@ApiImplicitParam():用于方法表示单独的请求参数
@ApiImplicitParams():用于方法,包含多个 @ApiImplicitParam
3. 使用
3.1 添加依赖
<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>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.8.5</version>
</dependency>
3.2 添加配置文件
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2Config {
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("后台API文档")
.description("后台API文档")
.version("1")
.contact(new Contact("Java","", ""))
.build();
}
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// true-开启文档;false-关闭文档
// .enable(false)
.groupName("后台API v1")
.select()
.apis(RequestHandlerSelectors.basePackage("com.xxx.xxx.controller.v1.app"))
.paths(PathSelectors.any())
.build();
}
@Bean
public Docket createAppUserRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false)
.groupName("后台API v2")
.select()
.apis(RequestHandlerSelectors.basePackage("com.xxx.xxx.controller.v2.app"))
.paths(PathSelectors.any())
.build();
}
}
3.3 使用
entity:
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
@ApiModel("用户信息")
public class User {
@ApiModelProperty("用户id")
private String id;
@ApiModelProperty("登录账号")
private String loginId;
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("登录密码")
private String password;
@ApiModelProperty("性别")
private Integer gender;
@ApiModelProperty("电话")
private String phone;
@ApiModelProperty("邮箱")
private String email;
@ApiModelProperty("部门id")
private String department_id;
}
dto和vo:
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
@ApiModel(value = "分页数据对象")
public abstract class SplitPageDTO {
@ApiModelProperty(value = "当前页", required = true)
private Integer page = 0;
@ApiModelProperty(value = "每页显示数目",example = "10", required = true)
private Integer pageSize = 10;
@ApiModelProperty(value = "查找顺序是否为正序", required = true)
private Boolean asc = false;
}
controller:
import com.xxx.xxx.dto.push.LoginDTO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
@RestController
@Api(tags="后台用户相关【/sysUser】")
@RequestMapping("/sysUser")
public class SysUserController {
@PostMapping("/passwordLogin")
@ApiOperation(value = "后台用户密码登录", notes = "使用密码登录")
public String passwordLogin(@RequestBody LoginDTO dto) {
return null;
}
}