openapi-interfaces: 自动生成 GET、POST、PUT 和 JSON Merge Patch 架构用于 OpenAPI

实验性。 详细信息可能有所变动。

此工具扩展了 OpenAPI 3.1.0，使其能够自动生成相关架构。具体来说，您可以定义一个单一的接口类型 Widget，并自动生成

• Widget（用于 GET 请求）
• WidgetPost
• WidgetPut
• WidgetMergePatch（用于使用 JSON Merge Patch 格式的 PATCH 请求，它基本上是一个很好的正式化的 "部分 PUT"）

安装

要安装最新版本，请确保您已安装 Rust 工具链。您可以使用这些说明进行安装。然后运行

cargo install -f openapi-interfaces

我们将在某个时候提供二进制文件。

用法

openapi-interfaces --help
openapi-interfaces api_with_interfaces.yml -o api.yml

OpenAPI 扩展

此工具定义了一个新的 components.interfaces 部分，允许指定 "接口" 类型。例如

components:
  # You can declare schemas normally if you wish.
  schemas: {}

  # But we also support interface definitions.
  interfaces:
    Resource:
      emit: false # Do not include this in generated output.
      members:
        id:
          required: true
          schema:
            # Normal OpenAPI / JSON Schema definitions.
            type: string
            format: uuid
    Widget:
      # Include all fields from `Resource`.
      $includes: "Resource"
      members:
        # We can override properties from `Resource` using JSON
        # Merge Patch syntax.
        id:
          schema:
            example: e35a3c8d-5486-49ec-9b23-6747afc19570
        name:
          required: true
          mutable: true
          schema:
            type: string
        comment:
          mutable: true
          schema:
            type: string
        readonly:
          required: true
          # This can't be updated once the object is created.
          mutable: false
          # But we do allow this to be set at creation time.
          # If omitted, `initializable` defaults to the value
          # of the `mutable` option.
          initializable: true
          schema:
            type: string

这将自动生成四个 Widget 类型

components:
  schemas:
    Widget: ...
    WidgetPost: ...
    WidgetPut: ...
    WidgetMergePatch: ...

有关完整定义，请参阅 example_output.yml。

引用接口

然后，我们可以使用新的 $interface 键，并选择合适的变体来引用接口

paths:
  /widgets:
    post:
      requestBody:
        required: true
        content:
          application/json:
              schema:
                # This becomes `$ref: "#/components/schemas/WidgetPost`.
                $interface: "Widget#Post"
      responses:
        201:
          content:
            application/json:
              schema:
                # This becomes `$ref: "#/components/schemas/Widget`.
                $interface: "Widget"

可能的选项包括

• Widget：由 GET 和其他提供从服务器获取完整资源的其他方法返回的类型。
• Widget#Post：传递给 POST 请求的类型。
• Widget#Put：传递给 PUT 请求的类型。也可以用作应用 #MergePatch 值的基本类型。
• Widget#MergePatch：一个可以传递给 PATCH 的 JSON Merge Patch 架构。
• Widget#SameAsInterface：**只能用于 components.interfaces 内部**。这是一个快捷值，表示“当生成 #Get 接口时，包含 $ref: "components.schemas.Widget。当生成 #Post 接口时，包含 $ref: "components.schemas.WidgetPost。"换句话说，使用与包含接口相同的变体选择器。当需要通过网络发送复合类型时非常有用。