在我们的传统项目中，对前后端的API接口约定，一般有写成接口文档，或者公司内部口头交流，或者其它方式，但这几种方式都给我们的协同工作中带来了或多或少的不便之处，那么就有了一些工具的出现来对我们的协同工作带来便利。这种工具选择面还是挺多的，有swagger，jdoc，apiDoc等。

目前我在工作中写得较多的就是API接口，项目大部分都采用springBoot编写，集成了swagger2来作为生成API+测试，总体上挺好使用的，话不多说，直接步入正题。

一、依赖包引入

pom.xml中引人依赖

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

二、配置

2.1 在springBoot配置文件application.yml中加入如下配置：

#swagger 配置
swagger: 
  title: API示例
  desc: 基于springBoot编写的RESful-API
  version: 0.0.1.SNAPSHOT
  termsOfServiceUrl: javascript:void(0)
  license: Apache 2.0
  licenseUrl: http://www.apache.org/licenses/LICENSE-2.0.html
  basePackage: com.restful.api.demo.web
  groupName: 默认API示例分组
  contactName: wendell
  contactUrl: https://github.com/wendell-dev/restful-api-demo.git
  contactEmail: 727169395@qq.com

2.2 新建配置类

类头部主要声明了配置注解和启用swagger2注解

/**
 * 对Swagger2的配置信息
 * 
 * @author wendell
 */
@Configuration
@EnableSwagger2
@ConfigurationProperties(prefix = "swagger")
public class Swagger2Config {
    private String title;
    private String desc;
    private String version;
    private String termsOfServiceUrl;
    private String license;
    private String licenseUrl;
    private String basePackage;
    private String groupName;
    private String contactName;
    private String contactUrl;
    private String contactEmail;

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title(title).description(desc).version(version).termsOfServiceUrl(termsOfServiceUrl)
                .licenseUrl(licenseUrl).license(license).contact(new Contact(contactName, contactUrl, contactEmail))
                .build();
    }

    @Bean
    public Docket swaggerApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName(groupName)
                .directModelSubstitute(LocalDate.class, String.class).genericModelSubstitutes(ResponseEntity.class)
                .useDefaultResponseMessages(false)
                .globalResponseMessage(RequestMethod.POST, customerResponseMessage())
                .globalResponseMessage(RequestMethod.GET, customerResponseMessage())
                .forCodeGeneration(true).select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any())
                .build();
    }

    private List<ResponseMessage> customerResponseMessage() {
        List<ResponseMessage> list = new ArrayList<>();
        list.add(new ResponseMessageBuilder().code(200).message("请求成功").build());
        list.add(new ResponseMessageBuilder().code(201).message("资源创建成功").build());
        list.add(new ResponseMessageBuilder().code(204).message("服务器成功处理了请求，但不需要返回任何实体内容").build());
        list.add(new ResponseMessageBuilder().code(400).message("请求失败,具体查看返回业务状态码与对应消息").build());
        list.add(new ResponseMessageBuilder().code(401).message("请求失败,未经过身份认证").build());
        list.add(new ResponseMessageBuilder().code(405).message("请求方法不支持").build());
        list.add(new ResponseMessageBuilder().code(415).message("请求媒体类型不支持").build());
        list.add(new ResponseMessageBuilder().code(500).message("服务器遇到了一个未曾预料的状况,导致了它无法完成对请求的处理").build());
        list.add(new ResponseMessageBuilder().code(503).message("服务器当前无法处理请求,这个状况是临时的，并且将在一段时间以后恢复").build());
        return list;
    }

    //  setter/getter略
}

三、controller中使用

需要在controller层的类头部以及方法头部侵入代码了，主要用到一些io.swagger.annotations下的注解

/**
 * 测试接口 - controller类
 *
 * @author wendell
 */
@Api(tags = "测试接口")
@RestController
@RequestMapping(value = "/tests")
public class TestController {

    @ApiOperation(value = "测试 - GET请求参数")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "编号", required = true, paramType = "query"),
        @ApiImplicitParam(name = "name", value = "名称", required = false, paramType = "query") 
    })
    @GetMapping
    public ResponseEntity<String> test(@RequestParam Long id, @RequestParam String name) {
        return ResponseEntity.ok("编号: " + id + "名称: " + name);
    }

}
    

四、启动springBoot应用

接着我们启动我们的springBoot应用，访问swagger2自带的入口页面地址 http://localhost/swagger-ui.html , 下图就是生成的API接口，可以点击左下方的 [Try it out!] 按钮进行http请求测试，非常方便。

swagger-ui

五、加入统一参数

大部分时候，我们编写的API接口都需要登录后访问，一般我们都是统一验证请求header里面的token参数，那么类似这种参数就应该统一处理，而不是在所有需要的controller方法中都加上token参数，类似下面这种 不恰当 用法：

@ApiOperation(value = "测试 - GET请求加入header参数")
@ApiImplicitParams({
    @ApiImplicitParam(name = "token", value = "请求token", required = true, paramType = "header"),
})
@GetMapping
public ResponseEntity<String> test(@RequestHeader String token) {
    return ResponseEntity.ok("token:" + token);
}

我们应该在swagger的配置类中统一处理token参数，只需要修改我们上面2.2步骤中Swagger2Config类即可，如下这样的方式：

@Bean
public Docket swaggerApi() {
    //  ==================== 需要的参数 START ==================== 
    List<Parameter> pars = new ArrayList<>();
    ParameterBuilder token = new ParameterBuilder();
    token.name("token").description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
    pars.add(token.build());
    //  ==================== 需要的参数 END ==================== 
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName(groupName)
            .globalOperationParameters(pars) // 全局参数
            .directModelSubstitute(LocalDate.class, String.class).genericModelSubstitutes(ResponseEntity.class)
            .useDefaultResponseMessages(false)
            .globalResponseMessage(RequestMethod.POST, customerResponseMessage())
            .globalResponseMessage(RequestMethod.GET, customerResponseMessage())
            .forCodeGeneration(true).select()
            .apis(RequestHandlerSelectors.basePackage(basePackage))
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any())
            .build();
}

接下来我们再次访问swagger2自带的入口页面地址，看看效果：

swagger-ui

可以看见，我们的接口中已经多了一个非必填的参数token，而且参数是在请求header中。

六、结束语

好了，关于springBoot集成swagger2的方式就介绍到这里，文中介绍的方式绝大部分方式都是基于我自己在工作中的使用方式，已经能够满足大部分的接口文档需求了。 当然还有一些高级点的特征没有介绍到，如分组之类，其实就是在配置文件上下文章，需要的时候自行google一下即可。