简介
Swagger不仅可以快速形成API接口文档，而且还可以通过它进行接口测试，使用非常方便快捷。
- 1.快速抽取API接口文档
- 2.接口快捷测试
快速集成
- 1.通过maven方式引入依赖
io.springfox
springfox-swagger2
2.6.1
io.springfox
springfox-swagger-ui
2.6.1
- 2.增加Swagger的配置文件
通过配置文件可以配置Swagger的api包扫码位置，也可以配置Swagger文档的标题，作者，描述等基本文档信息。
import org.springframework.beans.factory.annotation.Value;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("api文档标题")
.description("api文档描述")
.termsOfServiceUrl("http://baidu.com")//（不可见）条款地址
.version("1.0")
.build();
}
}
- 3.在Controller类中增加接口注解（提取API文档）
| 注解作用范围 | API | 使用位置 |
|---|---|---|
| 对象属性 | @ApiModelProperty | 用在出入参数对象的字段上 |
| 协议集描述 | @Api | 用于controller类上 |
| 协议描述 | @ApiOperation | 用在controller的方法上 |
| Response集 | @ApiResponses | 用在controller的方法上 |
| Response | @ApiResponse | 用在 @ApiResponses里边 |
| 非对象参数集 | @ApiImplicitParams | 用在controller的方法上 |
| 非对象参数描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法里边 |
| 描述返回对象的意义 | @ApiModel | 用在返回对象类上 |
paramType可选类型:
path 以地址的形式提交数据
query 直接跟参数完成自动映射赋值
body 以流的形式提交 仅支持POST
header 参数在request headers 里边提交
form 以form表单的形式提交 仅支持POST
代码示例:
@ApiOperation(value = "增加用户",notes = "增加用户")
@ResponseBody
@PostMapping("/add")
public int addUser(@RequestBody User user){
return userService.addUser(user);
}
@ApiOperation(value = "查询所有用户",notes = "查询所有用户信息",httpMethod = "GET",response = User.class,produces = "application/json")
@ApiImplicitParams({
@ApiImplicitParam(name = "pageNum", value = "分页页数", required = false, dataType = "int",paramType = "query"),
@ApiImplicitParam(name = "pageSize", value = "每分页数", required = false, dataType = "int",paramType = "query"),
})
@ResponseBody
@GetMapping("/all")
public List findAllUser(
@RequestParam(name = "pageNum", required = false, defaultValue = "1")
int pageNum,
@RequestParam(name = "pageSize", required = false, defaultValue = "10")
int pageSize){
//开始分页
PageHelper.startPage(pageNum,pageSize);
return userService.findAllUser(pageNum,pageSize);
}
传递进出参数对象 User类配置API注解
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel(value = "用户信息")
public class User {
@ApiModelProperty(value = "ID",required = true)
int id;
@ApiModelProperty(value = "用户ID",required = true)
String uid;
@ApiModelProperty(value = "用户名称",required = true)
String username;
@ApiModelProperty(value = "用户密码",required = true)
String password;
@ApiModelProperty(value = "用户手机号码",required = true)
String phone;
@ApiModelProperty(value = "用户Email",required = false)
String email;
//setter/getter.......
}
- 4.在应用程序Application启动类上添加注解
这个@EnableSwagger2注解千万别忘了加在启动类上
@SpringBootApplication
@EnableSwagger2//开启Swagger2
public class BaseframeApplication
{
public static void main(String[] args) {
SpringApplication.run(BaseframeApplication.class, args);
}
}
- 5.启动服务查看自动生成的API文档
访问 http://localhost:port/swagger-ui.html 可以看到刚刚配置的API文档
image.png
/user/add 接口中 ‘/user’ 是当前类上的路径。
我们不只可以查看API文档，还可以通过每个接口上的 Try it out!按钮 访问服务测试接口的有效性。