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

Question

假设我有一些简单的Order > OrderLines > Product在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

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

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

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

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

我是说，做这样的事有可能吗？

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

Answer 1

首先，始终将type: object添加到对象定义中；仅使用properties关键字不足以指示对象类型。type不是从其他关键字和 actually means "any type"推断出来的。

至于您的问题--当然，可以对单个属性定义进行$ref。您的例子几乎是正确的，您只需：

1. 将$ref放入参数schema中。
2. 将#components替换为#/components。
3. 将引用值(#/components/...)括在引号中，以防止它们被解析为YAML注释。

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

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

components:    
  schemas:
    OrderId:        # <-------
      type: integer
    OrderLineId:    # <-------
      type: integer

    Order:
      type: object
      required:
        - orderId
      properties:
        orderId:
          $ref: '#/components/schemas/OrderId'      # <-------
        ...
    OrderLine:
      type: object
      required:
        - orderLineId
        - product
        - price
      properties:
        orderLineId:
          $ref: '#/components/schemas/OrderLineId'  # <-------
        ...

paths:
    /orders/{orderId}/orderlines/{orderLineId}:
        get:
            operationId: getOrderLine
            parameters:
               - in: path
                 name: orderId
                 schema:
                   $ref: '#/components/schemas/OrderId'      # <-------
                 required: true
               - in: path
                 name: orderLineId
                 schema:
                   $ref: '#/components/schemas/OrderLineId'  # <-------
                 required: true