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按钮对后端服务进行在线测试；另一方面，其对于泛型参数也是支持的