@TOC
什么是 Swagger？
Swagger是一组围绕 OpenAPI 规范构建的开源工具，可帮助您设计、构建、记录和使用 REST API。主要的 Swagger 工具包括：
Swagger Editor – 基于浏览器的编辑器，您可以在其中编写 OpenAPI 规范。
Swagger UI – 将 OpenAPI 规范呈现为交互式 API 文档。
swagger2于17年停止维护，现在最新的版本为 Swagger3（Open Api3）。
依赖引入
我们可以去 mvnrepository（maven中央仓库） 搜索版本，但是建议不要用最新版
io.springfox
springfox-swagger2
2.9.2
io.swagger
swagger-models
io.swagger
swagger-models
1.5.21
io.springfox
springfox-swagger-ui
2.9.0
com.github.xiaoymin
swagger-bootstrap-ui
1.8.5
自定义属性配置 SwaggerProperties.class
根据自己的需求配置属性
package com.xxx.common.swagger.config;
import java.util.ArrayList;
import java.util.List;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
@Component
//application 配置文件路径
@ConfigurationProperties("swagger")
public class SwaggerProperties
{
/**
* 是否开启swagger
*/
private Boolean enabled;
/**
* swagger会解析的包路径
**/
private String basePackage = "";
/**
* swagger会解析的url规则
**/
private List basePath = new ArrayList<>();
/**
* 在basePath基础上需要排除的url规则
**/
private List excludePath = new ArrayList<>();
/**
* 标题
**/
private String title = "";
/**
* 描述
**/
private String description = "";
/**
* 版本
**/
private String version = "";
/**
* 许可证
**/
private String license = "";
/**
* 许可证URL
**/
private String licenseUrl = "";
/**
* 服务条款URL
**/
private String termsOfServiceUrl = "";
/**
* host信息
**/
private String host = "";
/**
* 联系人信息
*/
private Contact contact = new Contact();
/**
* 全局统一鉴权配置
**/
private Authorization authorization = new Authorization();
public Boolean getEnabled()
{
return enabled;
}
public void setEnabled(Boolean enabled)
{
this.enabled = enabled;
}
public String getBasePackage()
{
return basePackage;
}
public void setBasePackage(String basePackage)
{
this.basePackage = basePackage;
}
public List getBasePath()
{
return basePath;
}
public void setBasePath(List basePath)
{
this.basePath = basePath;
}
public List getExcludePath()
{
return excludePath;
}
public void setExcludePath(List excludePath)
{
this.excludePath = excludePath;
}
public String getTitle()
{
return title;
}
public void setTitle(String title)
{
this.title = title;
}
public String getDescription()
{
return description;
}
public void setDescription(String description)
{
this.description = description;
}
public String getVersion()
{
return version;
}
public void setVersion(String version)
{
this.version = version;
}
public String getLicense()
{
return license;
}
public void setLicense(String license)
{
this.license = license;
}
public String getLicenseUrl()
{
return licenseUrl;
}
public void setLicenseUrl(String licenseUrl)
{
this.licenseUrl = licenseUrl;
}
public String getTermsOfServiceUrl()
{
return termsOfServiceUrl;
}
public void setTermsOfServiceUrl(String termsOfServiceUrl)
{
this.termsOfServiceUrl = termsOfServiceUrl;
}
public String getHost()
{
return host;
}
public void setHost(String host)
{
this.host = host;
}
public Contact getContact()
{
return contact;
}
public void setContact(Contact contact)
{
this.contact = contact;
}
public Authorization getAuthorization()
{
return authorization;
}
public void setAuthorization(Authorization authorization)
{
this.authorization = authorization;
}
public static class Contact
{
/**
* 联系人
**/
private String name = "";
/**
* 联系人url
**/
private String url = "";
/**
* 联系人email
**/
private String email = "";
public String getName()
{
return name;
}
public void setName(String name)
{
this.name = name;
}
public String getUrl()
{
return url;
}
public void setUrl(String url)
{
this.url = url;
}
public String getEmail()
{
return email;
}
public void setEmail(String email)
{
this.email = email;
}
}
public static class Authorization
{
/**
* 鉴权策略ID，需要和SecurityReferences ID保持一致
*/
private String name = "";
/**
* 需要开启鉴权URL的正则
*/
private String authRegex = "^.*$";
/**
* 鉴权作用域列表
*/
private List authorizationScopeList = new ArrayList<>();
private List tokenUrlList = new ArrayList<>();
public String getName()
{
return name;
}
public void setName(String name)
{
this.name = name;
}
public String getAuthRegex()
{
return authRegex;
}
public void setAuthRegex(String authRegex)
{
this.authRegex = authRegex;
}
public List getAuthorizationScopeList()
{
return authorizationScopeList;
}
public void setAuthorizationScopeList(List authorizationScopeList)
{
this.authorizationScopeList = authorizationScopeList;
}
public List getTokenUrlList()
{
return tokenUrlList;
}
public void setTokenUrlList(List tokenUrlList)
{
this.tokenUrlList = tokenUrlList;
}
}
public static class AuthorizationScope
{
/**
* 作用域名称
*/
private String scope = "";
/**
* 作用域描述
*/
private String description = "";
public String getScope()
{
return scope;
}
public void setScope(String scope)
{
this.scope = scope;
}
public String getDescription()
{
return description;
}
public void setDescription(String description)
{
this.description = description;
}
}
} 详细配置
配置文件加上@EnableSwagger2、@Configuration 会自动开启配置，启动类不需要加任何注解
package com.xxx.interceptor.config;
import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
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.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
/**
*
* @author yaokun.zhang
*/
@Configuration
//是否开启swagger配置，生产环境需关闭
@Profile({"dev","local"})
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig {
/**
* 是否开启swagger配置，生产环境需关闭
*/
/*@Value("${swagger.enabled}")
private boolean enable;*/
/**
* 创建API
* http:IP:端口号/swagger-ui/ 原生地址
* http:IP:端口号/doc.html bootStrap-UI地址
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).pathMapping("/")
// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
/*.enable(enable)*/
.apiInfo(apiInfo())
// 设置哪些接口暴露给Swagger展示
.select()
// 扫描所有有注解的api，用这种方式更灵活
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 扫描指定包中的swagger注解
// .apis(RequestHandlerSelectors.basePackage("com.doctorcloud.product.web.controller"))
// 扫描所有 .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.regex("(?!/ApiError.*).*"))
.paths(PathSelectors.any())
.build()
// 支持的通讯协议集合
.protocols(newHashSet("https", "http"))
.securitySchemes(securitySchemes())
.securityContexts(securityContexts());
}
/**
* 支持的通讯协议集合
* @param type1
* @param type2
* @return
*/
private Set newHashSet(String type1, String type2){
Set set = new HashSet<>();
set.add(type1);
set.add(type2);
return set;
}
/**
* 认证的安全上下文
*/
private List securitySchemes() {
List securitySchemes = new ArrayList<>();
securitySchemes.add(new ApiKey("token", "token", "header"));
return securitySchemes;
}
/**
* 授权信息全局应用
*/
private List securityContexts() {
List securityContexts = new ArrayList<>();
securityContexts.add(SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.any()).build());
return securityContexts;
}
private List defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}
/**
* 添加摘要信息
*/
private ApiInfo apiInfo() {
// 用ApiInfoBuilder进行定制
return new ApiInfoBuilder()
// 设置标题
.title("接口文档")
// 描述
.description("描述")
// 作者信息
.contact(new Contact("doctorCloud", null, null))
// 版本
.version("版本号:V.1")
//协议
.license("The Apache License")
//协议url
.licenseUrl("")
.build();
}
}
swagger资源访问路径加入白名单
- /swagger-ui.html
- /doc.html
- /swagger-resources/**
- /v2/api-docs访问路径：
http:IP:端口号/swagger-ui.html 原生地址
http:IP:端口号/doc.html bootStrap-UI地址小技巧：
不建议使用swagger原生页面设置权限，建议使用doc页面设置token，搜索接口更方便