功能如此强大的 Swagger !
共 3768字,需浏览 8分钟
·
2020-12-26 23:31
前言
Swagger 是什么?
Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。
1.作用:
启动项目后在线自动生成API文档
在线高效调试
2.官网:https://swagger.ioknife4j 是什么?
为Java MVC框架集成Swagger的增强解决方案-前身是 swagger-bootstrap-ui
swagger-bootstrap-ui是springfox-swagger的增强UI实现,为Java开发者在使用Swagger的时候,能拥有一份简洁、强大的接口文档体验
1.作用:
接口排序
自定义文档说明
访问权限控制
请求参数缓存
调试动态请求参数
文档说明等
2.官网:https://doc.xiaominfo.com
整合一、pom.xml 引入 依赖
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger2artifactId>
<version>2.9.2version>
<exclusions>
<exclusion>
<groupId>io.swaggergroupId>
<artifactId>swagger-annotationsartifactId>
exclusion>
<exclusion>
<groupId>io.swaggergroupId>
<artifactId>swagger-modelsartifactId>
exclusion>
exclusions>
dependency>
<dependency>
<groupId>io.swaggergroupId>
<artifactId>swagger-annotationsartifactId>
<version>1.5.21version>
dependency>
<dependency>
<groupId>io.swaggergroupId>
<artifactId>swagger-modelsartifactId>
<version>1.5.21version>
dependency>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger-uiartifactId>
<version>2.9.2version>
dependency>
<dependency>
<groupId>com.github.xiaoymingroupId>
<artifactId>knife4j-spring-boot-starterartifactId>
<version>2.0.2version>
dependency>
二、创建swagger配置文件(swaggerConfig.java)
@Configuration // 声明为配置文件,让spring加载
@EnableSwagger2 // 支持swagger2插件配置
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class Swagger2Config {
// apiInfo对象主要是设置我们api文档的标题,描述,访问的地址,创建者等信息
@SuppressWarnings("deprecation")
@Bean
public ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("浓密秀发之谦先生的Api接口文档")
.description("快速进行Api接口调试")
.termsOfServiceUrl("127.0.0.1:8080")
.contact("Qian")
.version("1.0")
.build();
}
/**
* 创建API
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// .pathMapping("/dev-api")
// 用来创建该API的基本信息,展示在文档的页面中(自定义展示的信息)
.apiInfo(apiInfo())
// 设置哪些接口暴露给Swagger展示
.select()
// 扫描所有有注解的api,用这种方式更灵活
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 扫描指定包中的swagger注解
.apis(RequestHandlerSelectors.basePackage("cn.timer.api"))
// 扫描所有 .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any()).build()
/* 设置安全模式,swagger可以设置访问token */
.securitySchemes(securitySchemes()).securityContexts(securityContexts());
}
/**
* 安全模式,这里指定token通过Authorization头请求头传递
*/
private List securitySchemes() {
List apiKeyList = new ArrayList();
apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
return apiKeyList;
}
/**
* 安全上下文
*/
private List securityContexts() {
List securityContexts = new ArrayList<>();
securityContexts.add(SecurityContext.builder().securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("^(?!auth).*$")).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;
}
}
三、启动项目,访问 http://localhost:8089/doc.html (请求的端口看自身情况,我项目配置的是8089)
补充:API排序需要开启 增强模式
若无法访问或访问后API无法正常显示,原因有以下几点:
路径 http://localhost:8089/doc.html 被拦截
静态资源被后端拦截,如 js、html等
效果图
注解
tag排序:
@Api(tags = "1.0登录")
@Api(tags = "2.0注册")api排序:
@ApiOperationSupport(order = 1)
@ApiOperationSupport(order = 2)
整合过程中遇到的问题:
@ApiModelProperty注解example属性格式无法被解析
@ApiModelProperty(value = "是否默认", example = "["0","1"]")
example 的值 [“0”,“1”] 数组格式无法被解析,建议该为{}或字符串
原文链接:blog.csdn.net/weixin_38150130/article/details/105650695
关注GitHub今日热榜,专注挖掘好用的开发工具,致力于分享优质高效的工具、资源、插件等,助力开发者成长!
点个在看 你最好看