如何使用组件在 OPEN API 中创建示例？

Question

我的示例显示为参考而不是渲染。

我找到了一些关于使用组件为模式赋值的答案。但我不确定为什么它不能正常工作。任何建议将不胜感激

我的 API 规范看起来像这样

  responses:
    '200':
      description: Successful response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/deduction_charge'
          example:
            deduction_charge:
              $ref: '#/components/examples/deduction_charge'

我的组件看起来像这样

components:
  examples:
    deduction_charge:
      summary: Example deduction charge
      value:
        deduction_charge:
        - id: "ct_h5e599d3-0000-4d46-9a52-1a37e7b5b8ef"
          status: "SUCCESS"
          description: "Super HD plan"
          amount: 10000
          amount_refunded: 0
          currency: "JPY"
          deduction_token: "dt_f5e599d3-8b9e-4d46-9a52-1a37e7b5b8ef"
          metadata:
            customerID: "123"
            customerName: "Yamada Taro"
            transactionID: "A123"
          created_at: "2023-11-07T15:30:00.000+09:00"
          updated_at: "2023-11-07T15:30:00.000+09:00"

Answer 1

你应该使用

examples

（复数）

您的 yaml 缩进不正确

试试这个

openapi: 3.0.3
# need to add the rest of your structure here  ...
responses:
    '200':
      description: Successful response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/deduction_charge'
          examples:
            deduction_charge:
              $ref: '#/components/examples/deduction_charge'

components:
  examples:
    deduction_charge:
      summary: Example deduction charge
      value:
        deduction_charge:
          - id: "ct_h5e599d3-0000-4d46-9a52-1a37e7b5b8ef"
            status: "SUCCESS"
            description: "Super HD plan"
            amount: 10000
            amount_refunded: 0
            currency: "JPY"
            deduction_token: "dt_f5e599d3-8b9e-4d46-9a52-1a37e7b5b8ef"
            metadata:
              customerID: "123"
              customerName: "Yamada Taro"
              transactionID: "A123"
            created_at: "2023-11-07T15:30:00.000+09:00"
            updated_at: "2023-11-07T15:30:00.000+09:00"