localhost
Just So So ...
springboot使用swagger2避坑指南
September 1, 2020 · 默认分类 · 334次阅读在springboot种配置swagger2本身是比较简单的。基本按如下几步：
- maven中导入依赖
<!--添加Swagger-UI依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>- 配置swagger2的配置类
@Configuration //标记为配置类
@EnableSwagger2 //开启Swagger在线接口文档
public class SwaggerConfig {
/**
* 添加摘要信息(Docket)
* .groupName("XXXX")配置这个Docket的组名
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).groupName("组名:")
.apiInfo(new ApiInfoBuilder()
.title("嘉定台账系统")
.description("台账系统api")
//new Contact() 第一个参数是创建者,第二个是连接地址(可以不配),第三个参数是邮箱(可以不配)
.contact(new Contact("zy", "", "1178574705@qq.com"))
.version("版本号:1.0")
.build())
.select()
//扫描Api接口的包监听是哪一个路径的
.apis(RequestHandlerSelectors.basePackage("com.jiading.account.controller"))
.paths(PathSelectors.any())
.build();
}
}- 配置语言（国际化）（可选）
在resource目录下新建META-INF/resources目录，在该文件夹下新建swagger-ui.html文件，拷贝如下内容：
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Swagger UI</title>
<link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-32x32.png" sizes="32x32"/>
<link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-16x16.png" sizes="16x16"/>
<link href='webjars/springfox-swagger-ui/css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='webjars/springfox-swagger-ui/css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='webjars/springfox-swagger-ui/css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='webjars/springfox-swagger-ui/css/reset.css' media='print' rel='stylesheet' type='text/css'/>
<link href='webjars/springfox-swagger-ui/css/print.css' media='print' rel='stylesheet' type='text/css'/>
<script src='webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/jquery.slideto.min.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/lodash.min.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/backbone-min.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/swagger-ui.min.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/jsoneditor.min.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/marked.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lib/swagger-oauth.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/springfox.js' type='text/javascript'></script>
<!--国际化操作：选择中文版 -->
<script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>
</head>
<body class="swagger-section">
<div id='header'>
<div class="swagger-ui-wrap">
<a id="logo" href="http://swagger.io">嘉定平台开发API</a>
<form id='api_selector'>
<div class='input'>
<select id="select_baseUrl" name="select_baseUrl"></select>
</div>
<div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>
<div id='auth_container'></div>
<div class='input'><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div>
</form>
</div>
</div>
<div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div>
<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</body>
</html>完成以上三步后，正常情况下就能访问http://localhost:端口号/context路径/swagger-ui.html了
但事实上，其中的坑还是有不少的，列举一下我在使用过程中遇到的坑：
- swagger页面空白，只显示标题：
@Configuration
public class IntercepterConfig implements WebMvcConfigurer {
@Bean
public TokenInterceptor authenticationInterceptor() {
return new TokenInterceptor();
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(authenticationInterceptor())
.addPathPatterns("/**").excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**"); //配置排除路径
}
}也就是在spring拦截器中配置排除的路径。
- token授权不起作用
如果项目使用了token校验机制，那么需要在swagger里面配置一个全局token。但是按照网上大多数博客说的配置后，发现不起作用：
@Configuration //标记为配置类
@EnableSwagger2 //开启Swagger在线接口文档
public class SwaggerConfig {
/**
* 添加摘要信息(Docket)
* .groupName("XXXX")配置这个Docket的组名
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).forCodeGeneration(true)
.select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(regex("^.*(?<!error)$"))
.build()
.securitySchemes(securitySchemes())
.securityContexts(securityContexts());
}
private List<ApiKey> securitySchemes() {
return Lists.newArrayList(
new ApiKey("Access-Token", "Access-Token", "header"));
}
private List<SecurityContext> securityContexts() {
return Lists.newArrayList(
SecurityContext.builder()
.securityReferences(defaultAuth())
.build()
);
}
//增加全局认证
List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Access-Token", authorizationScopes));//验证增加（有许多教程说明中这个地方是Authorization,导致不能带入全局token，因为securitySchemes()方法中header写入token，所以这个地方我改为token就可以了(即两个地方名字一致)）
return securityReferences;
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("平台平台API")
.contact(new Contact(" 平台平台", "", "zyzengone@foxmail.com"))
.license("Copyright 2019 Jiading. All rights reserved.")
.licenseUrl("").version("2.0").build();
}