引用组件属性的OpenAPI路径参数

假设我在OpenAPI文档中有一些简单的订单>订单行>产品数据模型。 组件部分如下所示：

components:
  schemas:
    Order:
      required:
        - orderId
      properties:
        orderId:
          type: integer
        orderlines:
          type: array
          items:
            $ref: '#/components/schemas/OrderLine'
    OrderLine:
      required:
        - orderLineId
        - product
        - price
      properties:
        orderLineId:
          type: integer
        product:
          $ref: '#/components/schemas/Product'
        price:
          type: integer
    Product:
      required:
        - productId
        - name
      x-keys:
        - productId
      properties:
        productId:
          type: integer
        name:
          type: string

paths:
    /orders/{orderId}/orderlines/{orderLineId}:
        get:
            operationId: getOrderLine
            parameters:
               - in: path
                 name: orderId
                 schema:
                    type: integer
                 required: true
               - in: path
                 name: orderLineId
                 schema:
                    type: integer
                 required: true

paths:
    /orders/{orderId}/orderlines/{orderLineId}:
        get:
            operationId: getOrderLine
            parameters:
               - in: path
                 name: orderId
                 $ref: #components/schemas/Order/properties/orderId
                 required: true
               - in: path
                 name: orderLineId
                 $ref: #components/schemas/OrderLine/properties/orderLineId
                 required: true

构建路径以定义api以获取订单上的特定订单行时，如下所示：

components:
  schemas:
    Order:
      required:
        - orderId
      properties:
        orderId:
          type: integer
        orderlines:
          type: array
          items:
            $ref: '#/components/schemas/OrderLine'
    OrderLine:
      required:
        - orderLineId
        - product
        - price
      properties:
        orderLineId:
          type: integer
        product:
          $ref: '#/components/schemas/Product'
        price:
          type: integer
    Product:
      required:
        - productId
        - name
      x-keys:
        - productId
      properties:
        productId:
          type: integer
        name:
          type: string

paths:
    /orders/{orderId}/orderlines/{orderLineId}:
        get:
            operationId: getOrderLine
            parameters:
               - in: path
                 name: orderId
                 schema:
                    type: integer
                 required: true
               - in: path
                 name: orderLineId
                 schema:
                    type: integer
                 required: true

paths:
    /orders/{orderId}/orderlines/{orderLineId}:
        get:
            operationId: getOrderLine
            parameters:
               - in: path
                 name: orderId
                 $ref: #components/schemas/Order/properties/orderId
                 required: true
               - in: path
                 name: orderLineId
                 $ref: #components/schemas/OrderLine/properties/orderLineId
                 required: true

现在，定义的orderId参数实际上引用了Order组件的orderId属性。参数orderLineId也是如此，它引用组件OrderLine的orderLineId属性

那么，是否有可能在参数定义中实际引用这些属性，而不是复制属性的类型信息

我的意思是，有没有可能这样做：

components:
  schemas:
    Order:
      required:
        - orderId
      properties:
        orderId:
          type: integer
        orderlines:
          type: array
          items:
            $ref: '#/components/schemas/OrderLine'
    OrderLine:
      required:
        - orderLineId
        - product
        - price
      properties:
        orderLineId:
          type: integer
        product:
          $ref: '#/components/schemas/Product'
        price:
          type: integer
    Product:
      required:
        - productId
        - name
      x-keys:
        - productId
      properties:
        productId:
          type: integer
        name:
          type: string

paths:
    /orders/{orderId}/orderlines/{orderLineId}:
        get:
            operationId: getOrderLine
            parameters:
               - in: path
                 name: orderId
                 schema:
                    type: integer
                 required: true
               - in: path
                 name: orderLineId
                 schema:
                    type: integer
                 required: true

paths:
    /orders/{orderId}/orderlines/{orderLineId}:
        get:
            operationId: getOrderLine
            parameters:
               - in: path
                 name: orderId
                 $ref: #components/schemas/Order/properties/orderId
                 required: true
               - in: path
                 name: orderLineId
                 $ref: #components/schemas/OrderLine/properties/orderLineId
                 required: true

---

首先，始终在对象定义中添加

type:object

；仅使用

properties

关键字不足以指示对象类型。

类型

不是从其他关键字推断出来的，并且

至于你的问题-当然，可以

$ref

单独的属性定义。您的示例几乎正确，您只需：

将

$ref

放在参数

架构

内

将

#组件

替换为

#组件

将参考值（

#/components/…

）括在引号中，以防止它们被解析为YAML注释

路径：
/订单/{orderId}/orderlines/{orderLineId}：
获取：
操作ID:getOrderLine
参数：
-在：路径
名称：orderId
模式：
$ref:“#/components/schemas/Order/properties/orderId”
必填项：true
-在：路径
名称：orderLineId
模式：
$ref:“#/components/schemas/OrderLine/properties/orderLineId”
必填项：true

但是，引用特性定义并不常见，某些工具在处理此类引用时可能会遇到问题。最好为要定义的所有定义定义定义单独的模式

$ref

：

组件：
模式：
OrderId:#非常感谢您的透彻和清晰的解释！