Use formatting for examples in request/response fields

[caitlinnew]

Current Behavior

The issue we're hoping you all can help us with is that when we set existing models as data types for response and request fields the dev portal inlines the examples from those models in the docs without formatting. I've included some screenshots to show what I'm talking about. Also ideally we could toggle between the example we want when the model has two types of inputs.

How it looks now:

Expected Behavior

Ability to select which example is displayed

[chohmann]

@caitlinnew can you provide a spec and steps to reproduce this issue?

[chohmann]

I confirmed that this happens even for regular application/json content type.

Take this spec:

openapi: 3.1.0
x-stoplight:
  id: 6mf4vcvj66kh8
info:
  title: Elements 2372
  version: '1.0'
servers:
  - url: 'http://localhost:3000'
paths:
  /user:
    post:
      summary: Create New User
      operationId: post-user
      responses:
        '200':
          description: User Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
        '400':
          description: Missing Required Information
        '409':
          description: Email Already Taken
      requestBody:
        content:
          application/json:
            schema:
              type: object
              examples:
                requestBody:
                  value:
                    firstName: Bob
                    lastName: Fellow
                    email: [email protected]
                    dateOfBirth: '1996-08-24'
              properties:
                data:
                  $ref: '#/components/schemas/User'
                  x-stoplight:
                    id: o1mggl0nn1odc
        description: Post the necessary fields for the API to create a new user.
      description: Create a new user.
      x-stoplight:
        id: ocu3b0ud18xe7
components:
  schemas:
    User:
      title: User
      type: object
      description: ''
      x-examples:
        Alice Smith:
          id: 142
          firstName: Alice
          lastName: Smith
          email: [email protected]
          dateOfBirth: '1997-10-31'
          emailVerified: true
          signUpDate: '2019-08-24'
      properties:
        id:
          type: integer
          description: Unique identifier for the given user.
          x-stoplight:
            id: qigf5kctzwdnw
        firstName:
          type: string
          x-stoplight:
            id: w4sqjglg9i3hf
        lastName:
          type: string
          x-stoplight:
            id: ebqbath0sj27q
        email:
          type: string
          format: email
          x-stoplight:
            id: kmo01q1l9hi1f
        dateOfBirth:
          type: string
          format: date
          example: '1997-10-31'
          x-stoplight:
            id: gmfuq1p5cviu3
        emailVerified:
          type: boolean
          description: Set to true if the user's email has been verified.
          x-stoplight:
            id: tuxu2wit2lfj3
        createDate:
          type: string
          format: date
          description: The date that the user was created.
          x-stoplight:
            id: nft839lkojffc
      required:
        - id
        - firstName
        - lastName
        - email
        - emailVerified
      x-stoplight:
        id: fk45rrpbfvtcs
      examples:
        - id: 0
          firstName: string
          lastName: string
          email: [email protected]
          dateOfBirth: '1997-10-31'
          emailVerified: true
          createDate: '2019-08-24'

The example on the component schema is what is used in the examples section in docs. And no formatting is applied. If the ref'd schema does not have examples defined, we do not display the examples in docs.

So I'm guessing this is something we've never done and so this is kind of a feature request.