Swagger3.0官方starter诞生，可以扔掉那些野生starter了

2020-10-26 14:49:45 浏览数 (1)

Swagger3.0官方starter诞生，可以扔掉那些野生starter了

swagger介绍

对于 Rest API 来说很重要的一部分内容就是文档，Swagger 为我们提供了一套通过代码和注解自动生成文档的方法，这一点对于保证 API 文档的及时性将有很大的帮助。

Swagger 是一套基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。

OAS本身是一个API规范，它用于描述一整套API接口，包括一个接口是哪种请求方式、哪些参数、哪些header等，都会被包括在这个文件中。它在设计的时候通常是YAML格式，这种格式书写起来比较方便，而在网络中传输时又会以json形式居多，因为json的通用性比较强。

Swagger 主要包含了以下三个部分：

  • Swagger Editor：基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范。
  • Swagger UI：它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档，后文我将使用浏览器来查看并且操作我们的 Rest API。
  • Swagger Codegen：它可以通过为 OpenAPI（以前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。

springfox介绍

由于Spring的流行，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来，而springfox则是从这个组件发展而来。

通常SpringBoot项目整合swagger需要用到两个依赖：springfox-swagger2和springfox-swagger-ui，用于自动生成swagger文档。

  • springfox-swagger2：这个组件的功能用于帮助我们自动生成描述API的json文件
  • springfox-swagger-ui：就是将描述API的json文件解析出来，用一种更友好的方式呈现出来。

SpringFox 3.0.0 发布

官方说明：

❝ SpringFox 3.0.0 发布了，SpringFox 的前身是 swagger-springmvc，是一个开源的 API doc 框架，可以将 Controller 的方法以文档的形式展现。 ❞

❝ 首先，非常感谢社区让我有动力参与这个项目。在这个版本中，在代码、注释、bug报告方面有一些非常惊人的贡献，看到人们在问题论坛上跳槽来解决问题，我感到很谦卑。它确实激励我克服“困难”，开始认真地工作。有什么更好的办法来摆脱科维德的忧郁！ ❞

❝ 注意：这是一个突破性的变更版本，我们已经尽可能地保持与springfox早期版本的向后兼容性。在2.9之前被弃用的api已经被积极地删除，并且标记了将在不久的将来消失的新api。所以请注意这些，并报告任何遗漏的内容。 ❞

新特性：

  • Remove explicit dependencies on springfox-swagger2
  • Remove any @EnableSwagger2… annotations
  • Add the springfox-boot-starter dependency
  • Springfox 3.x removes dependencies on guava and other 3rd party libraries (not zero dep yet! depends on spring plugin and open api libraries for annotations and models) so if you used guava predicates/functions those will need to transition to java 8 function interfaces.

此版本的亮点：

  • Spring5，Webflux支持（仅支持请求映射，尚不支持功能端点）。
  • Spring Integration支持（非常感谢反馈）。
  • SpringBoot支持springfox Boot starter依赖性（零配置、自动配置支持）。
  • 具有自动完成功能的文档化配置属性。
  • 更好的规范兼容性与2.0。
  • 支持OpenApi 3.0.3。
  • 零依赖。几乎只需要spring-plugin，swagger-core ，现有的swagger2注释将继续工作并丰富openapi3.0规范。

兼容性说明：

  • 需要Java 8
  • 需要Spring5.x（未在早期版本中测试）
  • 需要SpringBoot 2.2 （未在早期版本中测试）

注意：

应用主类增加注解@EnableOpenApi，删除之前版本的SwaggerConfig.java。

启动项目，访问地址：http://localhost:8080/swagger-ui/index.html，注意2.x版本中访问的地址的为http://localhost:8080/swagger-ui.html

整合使用

Maven项目中引入springfox-boot-starter依赖：

代码语言：javascript复制
<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 中做了如下的事：

  • 去掉了啰嗦的pom依赖，包括springfox-swagger2
  • 干掉了@EnableSwagger2注解，零配置
  • 去掉了不少依赖，比如guava，更清爽

其实，所有的事情都是在AutoConfig文件里做的，就像其他starter做的事情一样。从源码中，我们发现swagger和ui组件默认都是开启的。

springfox.documentation.enabled 配置，可以一键关掉它。springfox.documentation.swagger-ui.enabled 参数，可以控制ui的展示。

从 Swagger 的依赖中，我们看到了一个比较有意思的概念：openAPI。这玩意，竟然也有 Specification 了。可见，文档不仅仅在老掉牙的项目类公司，在互联网中也是痛点。

https://swagger.io/specification/

文章很长，感兴趣的可以访问上面的网址到它们官网上查看详细内容。

关于权限认证

当然，变化也是有的。如果你的项目中用到了Spring Security这种权限控制组件，不要忘了添加白名单。类似于下面这种。

代码语言：javascript复制
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文件了。下面是完整代码。

代码语言：javascript复制
@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。类似于下面这种：

配置如下：

代码语言：javascript复制
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());
}

使用下面的代码用起来就可以了。

代码语言：javascript复制
.globalRequestParameters(globalRequestParameters());

最后

总之，整体感觉还是很不错的。可能是我的错觉，我觉得页面也流畅了不少。但由于新版本还是比较新，有不少细小的bug。比如Auth页面成功了，但在curl的请求参数里并没有值。

不过，瑕不掩瑜，swagger3 还是值得一试。更何况，它的改动代价，几乎没有。

java json spring api openapi

0 人点赞