在我们的传统项目中，对前后端的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: wendell-dev@foxmail.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一下即可。
