Springboot 2 以上版 集成 swagger2
swagger自带的ui挺弟弟的,网上看到了大佬写的不错.
增强版来源 https://doc.xiaominfo.com/guide/useful.html
1.依赖配置
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
注:如果和你的springboot 核心依赖冲突 导入以下依赖
<dependency>
<groupId>org.springframework.plugin</groupId>
<artifactId>spring-plugin-core</artifactId>
<version>1.2.0.RELEASE</version>
</dependency>
<dependency>
<groupId>org.springframework.plugin</groupId>
<artifactId>spring-plugin-metadata</artifactId>
<version>1.2.0.RELEASE</version>
</dependency>
2.配置config
其实配置 和swagger配置一模一样,增强版本有些其他的 功能。
@Configuration
@EnableSwagger2
//使用增强功能
@EnableSwaggerBootstrapUI
public class SwaggerConfig {
/** 扫包根路径 **/
//默认业务代码扫包路径
private final String defaultPackage = "com.xxxxx.xxx";
private final String defaultGroupName = "业务代码组";
//自定义扫包路径(我定义了一个系统级别代码)
private final String systemPackage= "com.xxxxx.xxx";
private final String systemGroupName = "系统管理组";
//标题
private final String title = "xxxxx系统";
//描述
private final String description = "xxxxm描述";
//termsOfServiceUrl
private final String termsOfServiceUrl = "xxxxx";
private final String version = "1.0";
//消息体对象
private final String resp = "ResponseMsg";
@Bean(value = "defaultApi")
public Docket createRestApi() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.groupName(defaultGroupName)
.select()
.apis(RequestHandlerSelectors.basePackage(defaultPackage))
.paths(PathSelectors.regex("/api.*"))
.build();
return buildDefaultApi(docket);
}
@Bean(value = "systemApi")
public Docket systemApi() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.groupName(systemGroupName)
.select()
.apis(RequestHandlerSelectors.basePackage(systemPackage))
.paths(PathSelectors.regex("/sys.*"))
.build();
return buildDefaultApi(docket);
}
/**
* 默認配置
* @param docket
* @return
*/
public Docket buildDefaultApi(Docket docket){
List<ResponseMessage> responseMessageList = new ArrayList<>();
responseMessageList.add(new ResponseMessageBuilder().code(404).message("找不到资源").responseModel(new ModelRef(resp)).build());
responseMessageList.add(new ResponseMessageBuilder().code(400).message("参数校验异常").responseModel(new ModelRef(resp)).build());
responseMessageList.add(new ResponseMessageBuilder().code(401).message("沒有登錄憑證/授權碼過期").responseModel(new ModelRef(resp)).build());
responseMessageList.add(new ResponseMessageBuilder().code(500).message("服务器内部错误").responseModel(new ModelRef(resp)).build());
responseMessageList.add(new ResponseMessageBuilder().code(402).message("無效權限").responseModel(new ModelRef(resp)).build());
docket.apiInfo(apiInfo())
.globalResponseMessage(RequestMethod.GET, responseMessageList)
.globalResponseMessage(RequestMethod.POST, responseMessageList)
.globalResponseMessage(RequestMethod.PUT, responseMessageList)
.globalResponseMessage(RequestMethod.DELETE, responseMessageList)
.securityContexts(Lists.newArrayList(securityContext())).securitySchemes(Lists.<SecurityScheme>newArrayList(apiKey()));
return docket;
}
/**
* 登錄auto配置
* @return
*/
private ApiKey apiKey() {
return new ApiKey("BearerToken", "Authorization", "header");
}
private SecurityContext securityContext() {
return SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("/.*"))
.build();
}
List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
return Lists.newArrayList(new SecurityReference("BearerToken", authorizationScopes));
}
/**
* apiInfo
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(title)
.description(description)
.termsOfServiceUrl(termsOfServiceUrl)
.version(version)
.contact("xxx")
.build();
}
}
这样就配好了,如果系统做了权限配置 开放以下路径白名单
/swagger-resources
/v2/api-docs
/v2/api-docs-ext
/doc.html
/webjars/**
注:主页地址 api地址为 /doc.html 非 /swagger-ui.html
3.增强功能
3.1访问权限控制
swagger.production=true
开启生产环境,屏蔽Swagger所有资源接口,关闭皆可以访问。
3.2访问页面加权控制
## 开启Swagger的Basic认证功能,默认是false
swagger.basic.enable=true
## Basic认证用户名
swagger.basic.username=admin
## Basic认证密码
swagger.basic.password=admin.xxx
4.界面风格(建议直接看knife4j官网,我都是直接抄的)
我的欣赏水平觉得 比 原本ui好看。
参考资料地址 :
https://doc.xiaominfo.com