为什么使用Swagger?
Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口,可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似,Swagger 消除了调用服务时可能会有的猜测。
Swagger 的优势:
1.支持 API 自动生成同步的在线文档:使用 Swagger 后可以直接通过代码生成文档,不再需要自己手动编写接口文档了,对程序员来说非常方便,可以节约写文档的时间去学习新技术。
2.提供 Web 页面在线测试 API:光有文档还不够,Swagger 生成的文档还支持在线测试。参数和格式都定好了,直接在界面上输入参数对应的值即可在线测试接口。
使用Swagger
导入相应依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
创建SwaggerConfig文件
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//swagger测试的controller路径
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build()
//下面两行为header中的Authorization认证,如不需要可不添加
.securitySchemes(securitySchemes())
.securityContexts(securityContexts());
}
//在测试界面简单进行描述
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("APIs")
.description("api接口文档")
.version("1.0")
.build();
}
private List<ApiKey> securitySchemes() {
//设置请求头信息
List<ApiKey> result = new ArrayList<>();
ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");
result.add(apiKey);
return result;
}
private List<SecurityContext> securityContexts() {
//设置需要登录认证的路径
List<SecurityContext> result = new ArrayList<>();
result.add(getContextByPath("/*/.*"));
return result;
}
private SecurityContext getContextByPath(String pathRegex){
return SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex(pathRegex))
.build();
}
//设置为全局调用,在测试界面输入一个Authorization值,后面测试的接口都将添加Authorization
private List<SecurityReference> defaultAuth() {
List<SecurityReference> result = new ArrayList<>();
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
result.add(new SecurityReference("Authorization", authorizationScopes));
return result;
}
}
使用Swagger进行接口测试
创建测试接口
@RestController
@Api(tags = "测试")
@RequestMapping("/test")
public class TestController {
@GetMapping("/testSwagger")
@ApiOperation(value = "swagger测试")
public String swagger(){
return "hello, swagger!";
}
@GetMapping("/testToken")
@ApiOperation(value = "swagger中token测试")
public String token(HttpServletRequest httpServletRequest){
//返回请求头中Authorization的值
if(httpServletRequest.getHeader("Authorization") == null){
return "Authorization is null";
}
return httpServletRequest.getHeader("Authorization");
}
}
默认的测试路径为:本机ip地址:port/swagger-ui.html
如 http://localhost:8080/swagger-ui.html
测试第一个接口
返回”hello, swagger!“
测试成功
测试第二个接口
当没有添加Authorization值时
返回”Authorization is null“
当添加Authorization值时
返回填入的Authorization对应值