时间戳

首页 > 解决方案 > 在 OpenAPI 中，我可以使用常规模式组件作为参数吗？

openapi - 在 OpenAPI 中，我可以使用常规模式组件作为参数吗？

问题描述

我在我的 API 中定义了一个带有路径参数的端点。

该参数的有效值已表示为枚举，我已将其定义为模式组件并在响应中使用。

两个问题：

  1. 如果您可以只使用对该架构组件的引用作为参数，为什么还要设置专用的参数组件，而不是使用可以在任何地方重复使用的通用架构组件？
  2. 如果你应该使用参数而不是通用模式，你可以创建一个引用模式组件的参数组件吗？我找不到任何可以通过验证的语法来执行此操作。

我会在这里粘贴我的定义，但我找不到任何不会造成可怕混乱的格式选项。

标签： openapi

解决方案

如果您可以只使用对该架构组件的引用作为参数，为什么还要设置专用的参数组件，而不是使用可以在任何地方重复使用的通用架构组件？

参数定义具有模式中不存在的附加属性，例如请求中的参数位置（in: path、in: query等）、数组和对象值的序列化方法等。Aschema只是参数属性之一，但仅模式并不能提供足够的信息来有效地描述参数。

您可以创建一个引用模式组件的参数组件吗？

是的。参数有一个schema，它可以是一个内联模式或一个$ref：

paths:
  /something/{role}:
    get:
      parameters:
        - $ref: '#/components/parameters/role'
...

components:
  parameters:
    role:
      in: path
      name: role
      required: true
      schema:
        $ref: '#/components/schemas/UserRole'  # <-----

  schemas:
    UserRole:
      type: string
      enum: [user, admin]

推荐阅读