How to create examples in OpenAPI using components?

Question

My example is showing up as ref instead of getting rendered.

I found some answer about assigning the keyword value to the schema in components. I'm not sure why it's not working correctly.

Response description

  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

You should use examples(plural)

Your yaml indentation was incorrect

Try this

openapi: 3.0.3
info:
  title: test
  version: "1"
servers:
  - url: https://www.example.com/v1
paths:
  '/thing':
    get:
      summary: thing api
      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"
  schemas:
    deduction_charge:
      type: object
      properties:
        deduction_charge:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              status:
                type: string
              description:
                type: string
              amount:
                type: number
              amount_refunded:
                type: number
              currency:
                type: string
              deduction_token:
                type: string
              metadata:
                type: object
                properties:
                  customerID:
                    type: string
                  customerName:
                    type: string
                  transactionID:
                    type: string
              created_at:
                type: string
                format: date-time
              updated_at:
                type: string
                format: date-time