什么是OpenAPI？

OpenAPI 规范（以前称为 Swagger 规范）是 REST API 的 API 描述格式。

OpenAPI 规范（OAS），是定义一个标准的、与具体编程语言无关的RESTful API的规范。OpenAPI 规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。如果您在定义您的 API 时做的很好，那么使用 API 的人就能非常轻松地理解您提供的 API 并与之交互了。

如果您遵循 OpenAPI 规范来定义您的 API，那么您就可以用文档生成工具来展示您的 API，用代码生成工具来自动生成各种编程语言的服务器端和客户端的代码，用自动测试工具进行测试等等。

什么是swagger？

Swagger 是一组围绕 OpenAPI 规范构建的开源工具，可以帮助您设计、构建、记录和使用 REST API。主要的 Swagger 工具包括：

  • Swagger Editor – 基于浏览器的编辑器，您可以在其中编写 OpenAPI 定义。
  • Swagger UI – 将 OpenAPI 定义呈现为交互式文档。
  • Swagger Codegen – 从 OpenAPI 定义生成服务器存根和客户端库。
  • Swagger Editor Next （beta） – 基于浏览器的编辑器，您可以在其中编写和查看OpenAPI和AsyncAPI定义。
  • Swagger Core – 与 Java 相关的库，用于创建、消费和使用 OpenAPI 定义。
  • Swagger Parser – 用于解析 OpenAPI 定义的独立库
  • Swagger APIDom – 提供单一的统一结构，用于跨各种描述语言和序列化格式描述 API。

为什么要使用 OpenAPI？

API描述自身结构的能力是OpenAPI中所有令人敬畏的根源。编写完成后，OpenAPI 规范和 Swagger 工具可以通过各种方式进一步推动您的 API 开发：

  • 设计优先用户：使用 Swagger Codegen 为您的 API 生成服务器存根。剩下的唯一事情就是实现服务器逻辑 - 您的 API 已准备好上线！
  • 使用 Swagger Codegen 为您的 API 生成 40 多种语言的客户端库。
  • 使用 Swagger UI 生成交互式 API 文档，让您的用户直接在浏览器中试用 API 调用。
  • 使用该规范将与 API 相关的工具连接到您的 API。例如，将规范导入 SoapUI 以为您的 API 创建自动测试。
  • 还有更多！查看与 Swagger 集成的开源和商业工具。

swagger.io官网

springdoc-openapi

Springfox vs Springdoc

OpenAPI3的规范，目前针对Java的Spring Boot项目，主要支持的有2个版本

  • springfox 3.0.0： 同时兼容OpenAPI2以及OpenAPI3，但是停更很久了

  • springdoc-openapi： 兼容OpenAPI3规范，更新速度频繁

  1. Springfox
    Springfox其实是一个通过扫描代码提取代码中的信息，生成API文档的工具。API文档的格式不止Swagger的OpenAPI Specification，还有RAML，jsonapi，Springfox的目标同样包括支持这些格式。

  2. Springdoc
    Springdoc是一个java类库，用于自动产生Api文档，支持OpenApi 3.0。

  3. 二者关系
    Springdoc和Springfox比起来，Springdoc更为活跃。

springdoc-openapi

简介

springdoc-openapi Java 库有助于使用 Spring 引导项目自动生成 API 文档。 通过在运行时检查应用程序来根据 Spring 配置、类结构和各种注释推断 API 语义。

springdoc-openapi自动生成 JSON/YAML 和 HTML 格式 API 中的文档。 本文档可以通过使用 swagger-api 注释的评论来完成。

此库支持：

  • OpenAPI 3
  • 弹簧引导（v1、v2 和 v3）
  • JSR-303，专门用于@NotNull、@Min、@Max和@Size。
  • 招摇的用户界面
  • OAuth 2
  • GraalVM 原生镜像

使用

Maven项目中引入springdoc-openapi-ui依赖：

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

  • Replace swagger 2 annotations with swagger 3 annotations (it is already included with springdoc-openapi-ui dependency). Package for swagger 3 annotations is io.swagger.v3.oas.annotations.
    • @Api → @Tag
    • @ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
    • @ApiImplicitParam → @Parameter
    • @ApiImplicitParams → @Parameters
    • @ApiModel → @Schema
    • @ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
    • @ApiModelProperty → @Schema
    • @ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
    • @ApiParam → @Parameter
    • @ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

image-20230216210353911

  • If you’re using an object to capture multiple request query params, annotation that method argument with @ParameterObject
  • This step is optional: Only if you have multiple Docket beans replace them with GroupedOpenApi beans.

初始化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("springshop-public")
            .pathsToMatch("/public/**")
            .build();
}
@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
            .group("springshop-admin")
            .pathsToMatch("/admin/**")
            .addMethodFilter(method -> method.isAnnotationPresent(Admin.class))
            .build();
}

If you have only one Docket — remove it and instead add properties to your application.properties:

1
2
springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**
  • Add bean of OpenAPI type. See example:
1
2
3
4
5
6
7
8
9
10
11
@Bean
public OpenAPI springShopOpenAPI() {
    return new OpenAPI()
            .info(new Info().title("SpringShop API")
            .description("Spring shop sample application")
            .version("v0.0.1")
            .license(new License().name("Apache 2.0").url("http://springdoc.org")))
            .externalDocs(new ExternalDocumentation()
            .description("SpringShop Wiki Documentation")
            .url("https://springshop.wiki.github.org/docs"));
}