SpringBoot Swagger2 快速上手

曾经我们使用的接口文档，都是基于word格式，缺点太明显。文档每次更新需要手动发送给前端开发者，更新交流不及时、不能在线直接测试，可能存在多个模块的文档，不便管理。写接口文档描述也花时间，前端开发者看着文档也累、、、

so，我们team自己开发了一套接口文档插件，基于注解形式自动生成html文档。哇，不用写文档了，真tm开心，哈哈。

直到某年某月的某一天，发现了swagger这样的神器。比我们做的更大而全，也是开源项目，懒人开发的福音。

直接开始！pom中引入依赖：

       <dependency>  
            <groupId>io.springfox</groupId>  
            <artifactId>springfox-swagger2</artifactId>  
            <version>2.8.0</version>  
        </dependency>  
        <dependency>  
            <groupId>io.springfox</groupId>  
            <artifactId>springfox-swagger-ui</artifactId>  
            <version>2.8.0</version>  
        </dependency>  

在项目中添加Swagger配置类：

package org.jc.demo.config;

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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
 * Swagger 配置类<br/>
 * Author:杨杰超<br/>
 * Date:2018年6月18日 下午11:26:51 <br/>
 * Copyright (c) 2018, yangjiechao@dingtalk.com All Rights Reserved.<br/> 
 *
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        // 创建API基本信息
        return new Docket(DocumentationType.SWAGGER_2)
                // 选择那些路径和api会生成document
                .apiInfo(apiInfo()).select()
                // 扫描该包下的所有需要在Swagger中展示的API，@ApiIgnore注解标注的除外
                .apis(RequestHandlerSelectors.basePackage("org.jc.demo.controller"))
                 对所有api进行监控
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        // 创建API的基本信息，这些信息会在Swagger UI中进行显示
        return new ApiInfoBuilder()
                // API标题
                .title("测试文档神器Swagger APIs")
                // API描述
                .description("这里是描述信息")
                // 版本号
                .version("1.0").build();
    }

}

Docket、ApiInfoBuilder对象具体参数请查阅源码与相关资料，这里只提供最简单的实现。

然后添加Controller

@RestController
@Api(tags = "grab-service", description = "抓取服务相关接口")
public class TestController {
    @Autowired
    private TestService service;

    // 使用该注解描述接口方法信息
    @ApiOperation(value = "接口名称", notes = "接口的描述信息") 
    @ApiImplicitParams(
            {@ApiImplicitParam(name = "name", value = "名称", required = true, dataType = "String", paramType = "path")}
            )
    @RequestMapping(value = "/test/{name}", method = RequestMethod.GET)
    public String test(@PathVariable String name) {
        return service.test(name);
    }

常用注解： 
@Api()用于类；                                             表示标识这个类是swagger的资源 
@ApiOperation()用于方法；                         表示一个http请求的操作 
@ApiParam()用于方法，参数，字段说明；    表示对参数的添加元数据（说明或是否必填等） 
@ApiModel()用于类                                      表示对类进行说明，用于参数用实体类接收 
@ApiModelProperty()用于方法，字段           表示对model属性的说明或者数据操作更改 
@ApiIgnore()用于类，方法，方法参数           表示这个方法或者类被忽略 
@ApiImplicitParam() 用于方法                      表示单独的请求参数 

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

权威指南：github项目主页

就这样就可以在项目中直接使用Swagger生成接口文档了，

启动项目，直接访问:http://localhost:port/swagger-ui.html 查看效果吧。

我们在项目中很少这样用，感觉需要设置的东西太多了，精简了一些参数。效果如下：

@RestController
@RequestMapping(value = "/order", produces = "application/json")
@Api(description = "订单服务接口", tags = "api-order")
public class OrderController extends AbstractController {

    @Autowired
    private OrderService orderService;


    @ApiOperation(value = "订单支付", notes = "订单支付")
    @ApiResponses({
            @ApiResponse(code = 601, message = "请求参数错误"),
            @ApiResponse(code = 602, message = "系统未知异常")
            //
    })
    @RequestMapping(value = "/order/pay", method = {RequestMethod.POST})
    public BaseRespDto orderPay(@RequestBody OrderPayReqDto req) {
        return orderService.orderPay(req);
    }
}

参数详细注解在参数类中实现

BaseRespDto：

import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
public class BaseRespDto {
    
    @ApiModelProperty(notes = "结果描述")
    private String respMsg = "成功";
}

OrderPayReqDto：

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel("订单支付请求实体")
public class OrderPayReqDto extends BaseReqDto {

    @ApiModelProperty(notes = "订单ID")
    private Long orderId;
    // 省略其他参数
}

Swagger2 GitHub ： https://github.com/swagger-api/swagger-core