OpenApi VS Swagger

OpenApi

OpenAPI，全称为“OpenAPI Specification”，是一个用于描述和定义RESTful API的 开放标准 。前身就是Swagger规范。它以可读性强且易于理解的方式，提供了API的详细信息，包括端点、参数、请求和响应格式等。OpenAPI旨在促进API的开发、维护和使用过程中的标准化和自动化。OpenAPI规范使用JSON或YAML格式编写，使开发人员和API消费者能够更好地理解和使用API。

OpenAPI是 与编程语言和实现无关 的。它的主要目标是定义和描述RESTful API的结构、端点、请求和响应格式等内容，而不关注具体的编程语言、框架或技术细节。

OpenApi是业界真正的 API 文档标准，它因为被Linux列为API标准，从而成为行业标准。

Swagger

Swagger 是一个 API 文档维护组织，后来成为了 Open API 标准的主要定义者。于此同时，它也同样是一种规范（是OpenApi的前身），也是一个工具集，这两者相辅相成。它在制定了规范的同时，也提供了一套开发的工具。

现在最新的版本为17年发布的 Swagger3（Open Api3）。但是现在绝大部分项目还在用过时的 Swagger2（17年停止维护并更名为swagger3）。

二者关系

现在，Swagger 代指 OpenApi 2.0，是一个协议+工具的结合体。OpenApi 3.0后，以单纯的规范的形式出现，剥离具体的实现。也有人用Swagger 3.0来表示 OpenApi 3.0。

Specification 1.0 2.0 3.0 Governance
Swagger ✅ ✅ SmartBear
OpenAPI ✅ ✅ OAI

SpringFox VS SpringDoc

SpringFox

SpringFox 是 Spring 社区维护的一个项目（非官方），帮助使用者将 Swagger2 集成到 Spring 中。常常用于 Spring 中帮助开发者生成文档，并可以轻松的在Spring Boot中使用。截至2020年4月，都未支持 OpenAPI3 标准。国内绝大多数项目中使用的都是SpringFox的2.x版本。对应的Maven依赖是：

1
2
3
4
5
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

直到 2020.7.14 SpringFox 发布了 3.0 版本，增加了对 OpenAPI3 的支持。同时也增加了对Spring 5，Webflux（仅请求映射支持，尚不支持功能端点）的支持。这是唯一同时兼容 OpenAPI2 和 OpenAPI3 两种规范的版本。

但它只是昙花一现，之后就再也没有过更新。对应的Maven依赖是：

1
2
3
4
5
6
7
8
9
10
11
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<!--同时更新了SpringBoot的Starter-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

SpringDoc

SpringDoc也是 spring 社区维护的一个项目（非官方），帮助使用者将 OpenAPI3 集成到 Spring 中。相较 SpringFox来说，它的活跃度更高，更新速度频繁。它仅支持 OpenAPI3 规范 ，但 OpenAPI3 并未对 Swagger2 的注解做兼容，不易迁移。可能这也是在国内知名度低于SpringFox的原因之一。

除了不支持Swagger2以外（本身也是历史遗留物了），它的兼容性是当前所有方案中最好的。它对SpringBootSpring WebFlux甚至Spring Rest和Spring Native项目都有支持，是新开发项目的首选方案。它对应的Maven依赖是：

1
2
3
4
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
</dependency>

两者关系

SpringFox 是Swagger2 时代的产物，仅有一个3.0版本提供对 OpenAPI3.0 的支持，之后就再也没有更新。随着SpringBoot版本的提升，在之后也会遇到越来越多的兼容性问题，在新项目中使用SpringFox 绝不是一个好的选择。

SpringDoc生来就是为了实现OpenAPI3.0规范，并且目前保持着更新。顺应改变，尝试使用SpringDoc吧。

由SpringFox迁移至SpringDoc

依赖替换

  • SpringFox

    1
    2
    3
    4
    5
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>

  • SpringDoc

    1
    2
    3
    4
    <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
    </dependency>

注解替换

SpringFox SpringDoc
@Api @Tag
@ApiIgnore @Parameter(hidden = true) or @Hidden
@ApiModel @Schema
@ApiModelProperty @Schema
@ApiOperation(value = “foo”,notes = “bar”) @Operation(summary = “foo”,description = “bar”)
@ApiParam @Parameter
@ApiImplicitParam @Parameter
@ApiImplicitParams @Parameters

配置类替换

由Docket替换为OpenAPI或者GroupedOpenAPI

  • SpringFox

    1
    2
    3
    4
    5
    6
    7
    8
    9
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
            .apiInfo(apiInfo())
            .enable(enableSwagger)
            .select()
            .apis(RequestHandlerSelectors.basePackage("cn.edu.huel.controller"))
            .build()
    }

  • OpenAPI

    1
    2
    3
    4
    5
    6
    @Bean
    public OpenAPI api() {
    return new OpenAPI()
        .paths("")
        .info(info())
    }

  • GroupedOpenAPI

    1
    2
    3
    4
    5
    6
    7
    @Bean
    public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
    	.setGroup("spring-public")
    	.packagesToScan("com.example.controller")
    	.build();
    }

这样就可以实现从SpringFox到SpringDoc的迁移。

替换默认UI——Knife4j

swagger-bootstrap-ui

无论是SpringFox还是SpringDoc，使用的都是同一套UI。这套UI怎么说呢，挺好看的。

但是有点过于简约了，对Model的展示也是文本形式的，使用起来有那么一点麻烦的。

image-20230815210201322.png

这种Model展示形式可读性有些低。

image-20230815210452028.png

Knife4j

Knife4j是Swagger的增强版，无论是SpringFox还是SpringDoc它都有提供增强。也提供了对应的增强依赖，在这里我们只引入UI即可。

1
2
3
4
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-openapi3-ui</artifactId>
</dependency>

或者直接使用它提供的Starter

1
2
3
4
5
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

默认情况下我们不需要再进行额外配置，在项目的/doc.html就已经有对应的接口文档UI了。

image-20230815211309128.png

可以看到这个布局以及对Model的展示清晰了很多。

  • 可选操作：排除掉swagger-bootstrap-ui

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
        <exclusions>
            <exclusion>
                <dependency>
                    <groupId>org.webjars</groupId>
                    <artifactId>swagger-ui</artifactId>
                </dependency>
            </exclusion>
        </exclusions>
        <version>4.3.0</version>
    </dependency>