我用到的swagger 主要有三款产品,swagger editor,swagger ui 和swagger codegen。
swagger editor:主要是一个本地客户端,用来自己添加api,自己来测试,相当于一个api的可视化测试工具和定义工具吧。
swagger ui:主要用户嵌入到项目中,将所有的接口生成一个可视化的页面,方便前后端联调
swagger codegen:主要用于通过swagger来自动生成代码
我用的swagger ui主要在java项目中。将所有的http接口提供一个可视化页面。供前端同学看到,联调非常方便,所有的接口一目了然。
但是在使用swagger ui的时候,我有一个新的需求,就是我所有的接口都必须授权才能访问,即每个接口都必须添加一个header里的参数。
我在Java中用的swagger框架是springfox。springfox是比较新的,官方也一直在更新。java添加swagger我就不详细介绍了,这里只介绍如何在所有的swagger接口中默认都添加header参数
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// .apis(RequestHandlerSelectors.basePackage("com.zoo.lion.modules"))
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//只生成被Api这个注解注解过的类接口
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//只生成被ApiOperation这个注解注解过的api接口
.paths(PathSelectors.any())
.build()
.globalOperationParameters(setHeaderToken())
;
}
主要添加 globalOperationParameters(setHeaderToken())
private List<Parameter> setHeaderToken() {
ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<>();
tokenPar.name("X-Auth-Token").description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
pars.add(tokenPar.build());
return pars;
}
//header中的ticket参数非必填,传空也可以