Swagger 增强方案
内容:
- SpringBoot 项目中如何使用?
- Spring Security 项目中如何使用?
- 使用 knife4j 增强 Swagger
SpringBoot 项目中如何使用?
Swagger3.0 官方已经有了自己的 Spring Boot Starter,只需要添加一个 jar 包即可(SpringBoot 版本 2.3.6.RELEASE)。。
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
什么都不用配置!直接在浏览器中访问 :http://ip:port/swagger-ui/ 即可。
Spring Security 项目中如何使用?
如果你的项目使用了 Spring Security 做权限认证的话,你需要为 Swagger 相关 url 添加白名单。
String[] SWAGGER_WHITELIST = {
"/swagger-ui.html",
"/swagger-ui/*",
"/swagger-resources/**",
"/v2/api-docs",
"/v3/api-docs",
"/webjars/**"
};
@Override
protected void configure(HttpSecurity http) throws Exception {
http.cors().and()
// 禁用 CSRF
.csrf().disable()
.authorizeRequests()
// swagger
.antMatchers(SWAGGER_WHITELIST).permitAll()
......
}
另外,某些请求需要认证之后才可以访问,为此,我们需要对 Swagger 做一些简单的配置。
配置的方式非常简单,我提供两种不同的方式给小伙伴们。
- 登录后自动为请求添加 token。
- 为请求的 Header 添加一个认证参数,每次请求的时候,我们需要手动输入 token。
登录后自动为请求添加 token
通过这种方式我们只需要授权一次即可使用所有需要授权的接口。
/**
* @author shuang.kou
* @description swagger 相关配置
*/
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("github.javaguide.springsecurityjwtguide"))
.paths(PathSelectors.any())
.build()
.securityContexts(securityContext())
.securitySchemes(securitySchemes());
}
private List<SecurityScheme> securitySchemes() {
return Collections.singletonList(new ApiKey("JWT", SecurityConstants.TOKEN_HEADER, "header"));
}
private List<SecurityContext> securityContext() {
SecurityContext securityContext = SecurityContext.builder()
.securityReferences(defaultAuth())
.build();
return Collections.singletonList(securityContext);
}
List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope
= new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
return Collections.singletonList(new SecurityReference("JWT", authorizationScopes));
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Security JWT Guide")
.build();
}
}
为请求的 Header 添加一个认证参数
每次请求的时候,我们需要手动输入 token 到指定位置。
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("github.javaguide.springsecurityjwtguide"))
.paths(PathSelectors.any())
.build()
.globalRequestParameters(authorizationParameter())
.securitySchemes(securitySchemes());
}
private List<SecurityScheme> securitySchemes() {
return Collections.singletonList(new ApiKey("JWT", SecurityConstants.TOKEN_HEADER, "header"));
}
private List<RequestParameter> authorizationParameter() {
RequestParameterBuilder tokenBuilder = new RequestParameterBuilder();
tokenBuilder
.name("Authorization")
.description("JWT")
.required(false)
.in("header")
.accepts(Collections.singleton(MediaType.APPLICATION_JSON))
.build();
return Collections.singletonList(tokenBuilder.build());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Security JWT Guide")
.build();
}
}
使用 knife4j 增强 Swagger
- YApi :YApi 是一个可本地部署的、打通前后端及 QA 的、可视化的接口管理平台。可以帮助我们让 swagger 页面的体验更加友好,目前很多大公司都在使用这个开源工具。项目地址:https://github.com/YMFE/yapi 。使用方法:当 Swagger 遇上 YApi,瞬间高大上了!
- Knife4j :Swagger 生成 Api 文档的增强解决方案,前身是 swagger-bootstrap-ui 。官方文档:https://xiaoym.gitee.io/knife4j/documentation/ 。
根据官网介绍,knife4j 是为 Java MVC 框架集成 Swagger 生成 Api 文档的增强解决方案。
项目地址:https://gitee.com/xiaoym/knife4j 。
使用方式非常简单,添加到相关依赖即可(SpringBoot 版本 2.3.6.RELEASE)。
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>
完成之后,访问:http://ip:port/doc.html 即可。
效果如下。可以看出,相比于 swagger 原生 ui 确实好看实用了很多。
除了 UI 上的增强之外,knife4j 还提供了一些开箱即用的功能。
比如:搜索 API 接口 (knife4j
版本 >2.0.1 )
再比如:导出离线文档
通过 Knife4j
我们可以非常方便地导出 Swagger 文档 ,并且支持多种格式。
- markdown:导出当前逻辑分组下所有接口的 Markdown 格式的文档
- Html:导出当前逻辑分组下所有接口的 Html 格式的文档
- Word:导出当前逻辑分组下所有接口的 Word 格式的文档(自 2.0.5 版本开始)
- OpenAPI:导出当前逻辑分组下的原始 OpenAPI 的规范 json 结构(自 2.0.6 版本开始)
- PDF:未实现
以 HTML 格式导出
欢迎来到这里!
我们正在构建一个小众社区,大家在这里相互信任,以平等 • 自由 • 奔放的价值观进行分享交流。最终,希望大家能够找到与自己志同道合的伙伴,共同成长。
注册 关于