SpringBoot中Swagger集成
在前后端分离的大背景下，API接口就成为了连接前后端之间的关键纽带。为了更好管理接口文档，实现文档与代码的同步。这里我们引入、介绍Swagger框架，其可通过注解的方式快速完成接口文档
添加依赖
在POM添加如下依赖
<!-- Swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.0</version>
</dependency>
配置
Swagger的配置代码如下所示，可以看到也是很简单的
/**
* Swagger Config
*/
@Configuration
public class SwaggerConfig {
@Bean
public Docket docket(){
Docket docket = new Docket(SWAGGER_2)
// 项目信息
.apiInfo( apiInfo() )
// 设置应用上下文
.pathMapping("/")
// 是否允许访问Swagger页面, 生产环境需设为false
.enable( true )
.select()
// 按需设置需要生成接口文档的父包
.apis(RequestHandlerSelectors.basePackage("com.aaron"))
.build();
return docket;
}
/**
* 项目信息
* @return
*/
private ApiInfo apiInfo() {
Contact concat = new Contact("Aaron", null,null);
return new ApiInfoBuilder()
.title("Demo服务") // 标题
.description("基于SpringBoot的Demo") // 描述
.contact(concat) // 作者信息
.version("1.2") // 版本
.build();
}
}
在SpringBoot启动类上添加@EnableSwagger2注解即可
@SpringBootApplication
@EnableSwagger2
public class SpringBoot1Application {
public static void main(String[] args) {
SpringApplication.run(SpringBoot1Application.class, args);
}
}
由于测试服务运行在8080端口，故打开下面的地址即可看到Swagger的页面
http://localhost:8080/swagger-ui.html
效果如下
使用
通过Swagger的注解，即可快速便捷的生成接口文档。示例代码如下所示
/**
* 车辆管理 Controller
*/
@RestController
@RequestMapping("car")
@Api(tags = "车辆管理") // 定义Controller说明
public class CarController {
/**
* 保存车辆信息
* @param car
* @return
*/
@PostMapping("/save")
// 定义接口说明
@ApiOperation(value = "保存车辆信息", notes = "保存(添加/修改)车辆信息")
public HttpResponseResult<String> save(@RequestBody Car car) {
return null;
}
/**
* 根据ID获取车辆信息
* @param id
* @return
*/
@GetMapping("/findById")
// 定义接口说明
@ApiOperation(value = "根据ID获取车辆信息")
public HttpResponseResult<Car> findById(@ApiParam(value="车辆ID", required=true) @RequestParam Integer id) {
Car car = Car.builder()
.id(id)
.build();
return HttpResponseResult.<Car>builder().data(car).build();
}
/**
* 根据名称获取车辆信息
* @param name
* @return
*/
@GetMapping("/findByName")
// 定义接口说明
@ApiOperation(value = "根据名称获取车辆信息")
@ApiImplicitParam(name = "name",value = "名称",required = true)
public HttpResponseResult<Car> findByName(@RequestParam String name) {
Car car = Car.builder()
.name( name )
.build();
return HttpResponseResult.<Car>builder().data(car).build();
}
/**
* 根据条件删除
* @param name
* @param id
* @return
*/
@GetMapping("/deleteByParam")
// 定义接口说明
@ApiOperation(value = "根据条件删除")
@ApiImplicitParams({ // 通过 @ApiImplicitParams 定义多个入参说明
@ApiImplicitParam(name = "name",value = "名称",required = true),
@ApiImplicitParam(name = "id",value = "车辆ID",required = false)
})
public HttpResponseResult<Integer> deleteByParam(@RequestParam String name, @RequestParam Integer id) {
return null;
}
}
可以看到，对于入参说明的定义，可以通过多种方式，具体包括：@ApiParam、@ApiImplicitParam、@ApiImplicitParams等注解。特别的，对于对象(JSON格式)来说，可以通过@ApiModel、@ApiModelProperty注解定义对象、字段说明
/**
* 汽车
*/
@AllArgsConstructor
@NoArgsConstructor
@Data
@Builder
@ApiModel("汽车") // 定义对象说明
public class Car {
/**
* ID
*/
// 定义字段说明
@ApiModelProperty("车辆ID")
private Integer id;
/**
* 名称
*/
@ApiModelProperty("名称")
private String name;
/**
* 价格
*/
@ApiModelProperty("价格")
private Double price;
/**
* 数量
*/
// 通过设置hidden属性为true, 在接口文档中隐藏该字段
@ApiModelProperty(value="数量", hidden=true)
private Integer num;
}
...
@AllArgsConstructor
@NoArgsConstructor
@Data
@Builder
@ApiModel("HTTP响应结果")
public class HttpResponseResult<T> {
@ApiModelProperty("状态码")
private String code;
@ApiModelProperty("信息")
private String msg;
@ApiModelProperty("数据")
private T data;
}
访问Swagger页面，效果如下所示
具体就某个具体的接口来看。一方面，我们可以通过Try it out按钮对后端服务进行在线测试；另一方面，其对于泛型参数也是支持的
评论