Swagger allOf 的用法

Swagger allof 是 Swagger 规范的一个扩展,它允许我们在定义数据结构时,引用其他已定义的数据模型,以创建更复杂的数据结构。使用 allof 可以实现数据模型的继承和组合,这减少了冗余的定义,并提高了代码的可维护性和可读性。

用 Apifox,节省研发团队的每一分钟

Swagger allOf 的用法

免费使用 Apifox

相关推荐

最新文章

API

一体化协作平台

API 设计

API 文档

API 调试

自动化测试

API Mock

API Hub

立即体验 Apifox
目录

Swagger allofSwagger 规范的一个扩展,它允许我们在定义数据结构时,引用其他已定义的数据模型,以创建更复杂的数据结构。使用 allof 可以实现数据模型的继承和组合,这减少了冗余的定义,并提高了代码的可维护性和可读性。

swagger API 界面
Swagger

Swagger allof 使用场景

在以下情况下,使用 Swagger allof 功能是有意义的:

  1. 数据模型的继承:当我们需要定义一组数据模型,其中一些模型是另一些模型的扩展时,可以使用 allof 来实现继承关系。这在处理有层次结构的数据对象时尤为有用。
  2. 属性组合:有时我们需要根据不同的条件组合属性,而不是针对每种情况都定义多个模型。使用 allof 可以将一些通用的属性定义为公共模型,然后组合不同的模型,以实现灵活的属性组合。

Swagger allof 示例用法

下面是一个示例代码,演示了在 Swagger Editor 中如何使用 allof 功能。当你将下面的例子复制粘贴到 Swagger Editor 中时,你将看到一个基本示例,其中使用allof合并了多个对象定义。

openapi: 3.0.0
info:
  title: Employee API
  version: 1.0.0
paths:
  /employees/{id}:
    get:
      summary: Get employee by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeResponse'

components:
  schemas:
    Address:
      type: object
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string

    Person:
      type: object
      properties:
        name:
          type: string
        age:
          type: integer

    EmployeeResponse:
      allOf:
        - $ref: '#/components/schemas/Person'
        - type: object
          properties:
            address:
              $ref: '#/components/schemas/Address'
            salary:
              type: number

在上面的示例中,我们定义了一个简单的 Employee API。该 API 包含了一个 GET 请求路径/employees/{id},用于按照 ID 获取员工信息。对应的响应的模式是EmployeeResponse


EmployeeResponse模式中,我们使用allofPersonAddress模式合并到EmployeeResponse,以便获取到的员工信息包括了姓名、年龄、地址和薪水属性。


将这个例子复制粘贴到 Swagger Editor 中,你可以通过点击"Try this operation"按钮来测试 GET 请求,并查看响应的模式。

Swagger allof 示例
Swagger allof 示例

使用 Apifox 管理 API 文档

Swagger 管理接口有时很不方便,缺乏团队间的分享协作,所以我更推荐使用 Apifox


Apifox 是一个比 Postman 更强大的接口测试工具,Apifox = Postman + Swagger + Mock + JMeter,Apifox 支持调试 http(s)、WebSocket、Socket、gRPC、Dubbo 等协议的接口,并且集成了 IDEA 插件。在开发完接口后,可以通过 Apifox 的 IDEA 插件一键生成接口文档,多端同步,非常方便测试和维护。


在上面的例子中,就可以直接导入到 Apifox 测试。

将 Swagger 导出为 JSON

如下图所示,选择“Convert and save as JSON”,将 Swagger 文档导出为 JSON 文件。

将 Swagger 导出为 JSON
将 Swagger 导出为 JSON

将 Swagger 文件导入 Apifox

打开 Apifox,创建一个项目后,选择“项目设置->导入数据->OpenAPI/Swagger->文件导入”,将已导出的 Swagger 格式的 JSON 文件导入即可。

将 Swagger 文件导入 Apifox
将 Swagger 文件导入 Apifox

导入时,会有预览,可以选择导入全部,也可以选择性的导入接口。

接口导入预览
接口导入预览

导入成功之后,就可以选择一个环境来测试接口。如下图所示,接口成功返回数据:

Apifox 中调试 API
Apifox 中调试 API

注意事项

在使用 Swagger allof 功能时,需要注意以下事项:

  1. 顺序的重要性:在使用 allof 时,顺序是非常重要的。确保正确设置父模型的顺序,以便正确继承属性。
  2. 引用已定义的模型:尽可能地引用已经定义好的模型,而不是在每个模型中重复定义相同的属性。这样可以避免冗余定义,提高代码的可维护性。
  3. 版本兼容性:在组合模型时,需要注意模型之间的字段兼容性。确保父模型和子模型之间的字段类型和名称一致,以避免在后续版本中出现问题。

知识扩展:


参考链接:

Swagger 官方文档:https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/