Swagger3.0官方starter诞生,可以扔掉那些野生starter了
对于 Rest API 来说很重要的一部分内容就是文档,Swagger 为我们提供了一套通过代码和注解自动生成文档的方法,这一点对于保证 API 文档的及时性将有很大的帮助。
Swagger 是一套基于 OpenAPI 规范(OpenAPI Specification,OAS)构建的开源工具,可以帮助我们设计、构建、记录以及使用 Rest API。
OAS本身是一个API规范,它用于描述一整套API接口,包括一个接口是哪种请求方式、哪些参数、哪些header等,都会被包括在这个文件中。它在设计的时候通常是YAML格式,这种格式书写起来比较方便,而在网络中传输时又会以json形式居多,因为json的通用性比较强。
Swagger 主要包含了以下三个部分:
由于Spring的流行,Marty Pitt编写了一个基于Spring的组件swagger-springmvc,用于将swagger集成到springmvc中来,而springfox则是从这个组件发展而来。
通常SpringBoot项目整合swagger需要用到两个依赖:springfox-swagger2和springfox-swagger-ui,用于自动生成swagger文档。
官方说明:
❝ SpringFox 3.0.0 发布了,SpringFox 的前身是 swagger-springmvc,是一个开源的 API doc 框架,可以将 Controller 的方法以文档的形式展现。 ❞
❝ 首先,非常感谢社区让我有动力参与这个项目。在这个版本中,在代码、注释、bug报告方面有一些非常惊人的贡献,看到人们在问题论坛上跳槽来解决问题,我感到很谦卑。它确实激励我克服“困难”,开始认真地工作。有什么更好的办法来摆脱科维德的忧郁! ❞
❝ 注意:这是一个突破性的变更版本,我们已经尽可能地保持与springfox早期版本的向后兼容性。在2.9之前被弃用的api已经被积极地删除,并且标记了将在不久的将来消失的新api。所以请注意这些,并报告任何遗漏的内容。 ❞
新特性:
此版本的亮点:
兼容性说明:
注意:
应用主类增加注解@EnableOpenApi
,删除之前版本的SwaggerConfig.java。
启动项目,访问地址:http://localhost:8080/swagger-ui/index.html
,注意2.x版本中访问的地址的为http://localhost:8080/swagger-ui.html
整合使用
Maven项目中引入springfox-boot-starter依赖:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
在浏览器中访问:http://localhost:8080/swagger-ui/
即可。
有人说需要在主类上加入@EnableOpenApi注解,但其实是不需要的。
可以看到,Swagger3 在 SpringBoot 中的配置,简单了不是一点点。更重要的是 io.springfox 这样的包名,看起来就高大上,让人不由自主的产生信任的感觉。
简单来说,Swagger 在 3.0 中做了如下的事:
其实,所有的事情都是在AutoConfig
文件里做的,就像其他starter
做的事情一样。从源码中,我们发现swagger
和ui
组件默认都是开启的。
springfox.documentation.enabled
配置,可以一键关掉它。springfox.documentation.swagger-ui.enabled 参数,可以控制ui的展示。
从 Swagger 的依赖中,我们看到了一个比较有意思的概念:openAPI。这玩意,竟然也有 Specification 了。可见,文档不仅仅在老掉牙的项目类公司,在互联网中也是痛点。
https://swagger.io/specification/
文章很长,感兴趣的可以访问上面的网址到它们官网上查看详细内容。
当然,变化也是有的。如果你的项目中用到了Spring Security
这种权限控制组件,不要忘了添加白名单。类似于下面这种。
String[] SWAGGER_WHITELIST = {
"/swagger-ui.html",
"/swagger-ui/*",
"/swagger-resources/**",
"/v2/api-docs",
"/v3/api-docs",
"/webjars/**"
};
httpSecurity.cors()
.antMatchers(SWAGGER_WHITELIST).permitAll()
背后的swagger地址,你访问v2也成,访问v3也成。反正我导入yapi、rap2这种API管理平台,都行得通。
集成到是变得简单了,但ApiOperation这种注解,还是一如既往的丑啊。
有时候,我们使用了JWT这样的认证方式,就需要在请求的时候,在Header
构造一个token
。
Swagger
支持两种方式。
第一种,通过全局的 Auth
认证配置。
如上图,点击右上角的Auth按钮,可弹出对话框。
这个时候,你就需要搞一个SwaggerConfig文件了。下面是完整代码。
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.build()
.securitySchemes(security());
}
private List<SecurityScheme> security() {
ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");
return Collections.singletonList(apiKey);
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("mbye api")
.description("nothing here")
.version("1.0")
.build();
}
}
另外一种,就是在每次请求的时候,都需要手动输入一个token。类似于下面这种:
配置如下:
private List<RequestParameter> globalRequestParameters() {
RequestParameterBuilder parameterBuilder = new RequestParameterBuilder()
.in(ParameterType.HEADER)
.name("Authorization")
.required(false)
.query(param -> param.model(model -> model.scalarModel(ScalarType.STRING)));
return Collections.singletonList(parameterBuilder.build());
}
使用下面的代码用起来就可以了。
.globalRequestParameters(globalRequestParameters());
总之,整体感觉还是很不错的。可能是我的错觉,我觉得页面也流畅了不少。但由于新版本还是比较新,有不少细小的bug。比如Auth页面成功了,但在curl的请求参数里并没有值。
不过,瑕不掩瑜,swagger3 还是值得一试。更何况,它的改动代价,几乎没有。