swagger的应用

November 13, 2018
swgger spring security

1 引言

在文章[一篇用idea写的md文章]里已经提到过swagger,这篇介绍更多内容。

2 应用

2.1 引入

在pom.xml中添加依赖:

<!-- 整合swagger,用于生成接口 文档  http://localhost:8080/swagger-ui.html-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.7.0</version>
</dependency>

添加配置类:

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.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.List;

import static com.google.common.collect.Lists.newArrayList;

//对方法的注解有要求:
//@ApiOperation("获取用户信息")
//@ApiImplicitParam(name = "name", value = "用户名", dataType = "string", paramType = "query")
//@GetMapping("/test/{name}")
//上边的方法是用 @GetMapping 注解,如果只是使用 @RequestMapping 注解,不配置 method 属性,那么 API 文档会生成 7 种请求方式。
@Configuration
@EnableSwagger2
public class Swagger2Configuration {
	@Bean
	public Docket accessToken() {
		return new Docket(DocumentationType.SWAGGER_2)
				.groupName("api")// 定义组
			    .select() // 选择那些路径和 api 会生成 document
			    .apis(RequestHandlerSelectors.basePackage("com.xx.qingdu.controller")) // 拦截的包路径
			    .paths(PathSelectors.regex("/*/.*"))// 拦截的接口路径
			    .build() // 创建
				.securitySchemes(securitySchemes())
				.securityContexts(securityContexts())
			    .apiInfo(apiInfo()); // 配置说明
	}


	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()//
				.title("氢读后台接口")// 标题
				.description("相关接口的详细定义")// 描述
				.termsOfServiceUrl("http://qingdu.com")//
				.contact(new Contact("daniel", "http://qingdu.com", "136099332@qq.com"))// 联系
				.version("1.0")// 版本
				.build();
	}

	//https://www.jianshu.com/p/6e5ee9dd5a61
	//https://www.cnblogs.com/exmyth/p/7183753.html
	private List<ApiKey> securitySchemes() {
		return newArrayList(
			//2IMAAOG0lEVSAMzxBGuJ
			new ApiKey("X-YY-Id", "X-YY-Id", "header")
			, new ApiKey("X-YY-Sign", "X-YY-Sign", "header")
		);
	}
	//定义需要进行header验证的接口,不能支持HTTP METHOD过滤?
	private List<SecurityContext> securityContexts() {
		return newArrayList(
				SecurityContext.builder()
						.securityReferences(defaultAuth())

						.forPaths(PathSelectors.regex("/*.*"))
						//.forPaths(PathSelectors.regex("^(?!auth).*$"))
						.build()
		);
	}

	//header验证,这个auth会保存在页面session中,在不刷新页面的情况,其它接口可用
	List<SecurityReference> defaultAuth() {
		AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
		AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
		authorizationScopes[0] = authorizationScope;
		return newArrayList(
				new SecurityReference("X-YY-Id", authorizationScopes)
		, new SecurityReference("X-YY-Sign", authorizationScopes));
	}
}

header验证的效果如下:
header_auth.jpg


loading