Response example not rendering

[vectra-tme]

Response example not rendering

Response object is not rendering when configured as sister of schema and deletes properties when configured as daughter of schema

Q	A
Bug or feature request?	Bug
Which Swagger/OpenAPI version?	3.X
Which Swagger-UI version?	3.4.0
How did you install Swagger-UI?	github
Which browser & version?	Chrome 62
Which operating system?	Ubuntu 64

According to the docs, example should be a sister to schema when using $ref. When doing this, I do not get the substitution I would expect for count, next, and previous

      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Response'
                  - type: object
                    properties:
                      results:
                        type: array
                        items:
                            type: object
                            $ref: '#/components/schemas/Detection'
              example:
                count: 10
                next: "http://127.0.0.1/api/v2/detection?page=3&page_size=1"
                previous: "http://127.0.0.1/api/v2/detection?page=1&page_size=1"

When I move example to a daughter of schema, I get he substitution, but lose additional properties that were appended to the schema

      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Response'
                  - type: object
                    properties:
                      results:
                        type: array
                        items:
                            type: object
                            $ref: '#/components/schemas/Detection'
                example:
                  count: 10
                  next: "http://127.0.0.1/api/v2/detection?page=3&page_size=1"
                  previous: "http://127.0.0.1/api/v2/detection?page=1&page_size=1"

[hkosova]

This is a duplicate of #3437.

When I move example to a daughter of schema, I get he substitution, but lose additional properties that were appended to the schema

This is expected - according to the spec, the example SHALL override (not merged into) any lower-level examples and auto-generated examples.

Try moving your example into the Response schema - it should give the result you want.

[vectra-tme]

Couple of things:

• The response schema is common for multiple endpoinst, but has different values. As an example, for the detection endpoint, next would be http://127.0.0.1/api/v2/detction and for the host endpoint it would be http://127.0.0.1/api/v2/host. So I is there a way to customize the examples in the response schema so they are reflective of the endpoint they are referenced?
• Although moving the examples to the response schema does give me the substitution that I want, it also eliminates additional objects that are defined as part of each response in the allOf stanza (i.e. results). Is this expected behavior? I can understand losing the example, but I wouldn't expect to lose the schema.

Hopefully, this makes sense. If there is way I can achieve this through combining references, any help you can provide is greatly appreciated.

[webron]

There's no mix and match for examples. If you define an example, it will be used as-is as the value (whether valid or not). You should not expect the UI to use parts of the values from the example and parts generating from the model itself.

The only way to set an example value to specific parts of the model is by providing the example at the property level - however, once you define a top-level example it will override the property example, and the property examples would be applied to all places that reference that model.

As for creating similar examples but with slightly different values - you'd need to create a whole example for each one of those cases.

[vectra-tme]

That's fair, I will be happy to define examples for a full schema. The problem I am running into is that my response schema is built from two objects

              schema:
                allOf:
                  - $ref: '#/components/schemas/Response'
                  - type: object
                    properties:
                      results:
                        type: array
                        items:
                            type: object
                            $ref: '#/components/schemas/Detection'
                    required:
                      - results

as soon as I start to configure examples, the reference to the Response renders, but the results object gets dropped completely

[webron]

It would really help to see something more full than snippets.

[vectra-tme]

I am attaching my spec. if you view the spec as configured, you will get the full sample for GET /detections. But, if you uncomment lines 65-69, the example breaks the schema and only renders k/v pairs.

spec.txt

[webron]

Going over tickets again now for organization, and upon testing the definition as provided, it seems to behave as expected. It just renders the example as-is, which is what it's supposed to do.

[keenle]

The problem of not rendered examples for response object still exists. In example bellow I define Error model, and provide default example for Error model. Later, while referencing error model in responses: 404: content: applicatioin/json: schema: section, I provide custom examples in responses: 404: content: applicatioin/json: examples:. The problem is that provided examples do not render in Swagger UI; I still see generic model example instead of response specific examples. Full swagger definition bellow:

openapi: "3.0.0"

info:
  title: "BUG: Response object, media type specific example/examples does/do not render."
  version: v1

paths:

  /order/{orderId}/item/{itemId}:
  
    get:
      summary: Fetch order item details
      operationId: FetchOrderItem
      parameters:
      - name: orderId
        in: path
        required: true
        schema:
          type: string
      - name: itemId
        in: path
        required: true
        schema:
          type: string
      responses:
      
        '200':
          description: Item details
          content:
            application/json:
              schema:
                type: object
                
        '404':
          description: Order or item not found. See error message for more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                resource-not-found-example:
                  summary: Order with a given id not found.
                  value: 
                    {
                      "message": "Order with id cbc7e492-0960-4de9-bdc1-52eb227c7ced not found."
                    }
                sub-resource-not-found-example:
                  summary: Order tem with a given id not found.
                  value: 
                    {
                      "message": "Order item with id 8650374c-22b1-435b-9f22-a50c4b78848e not found."
                    }
                     
components:

  schemas:
    Error:
      type: object
      required:
      - message
      properties:
        message:
          description: Error message.
          type: string
      example:
        {
          "message": "Some generic error message."
        }

[keenle]

I assume that my previous message describes a bug since OpenAPI spec for Media Type Object says the following:

Examples of the media type. Each example object SHOULD match the media type and specified schema if present. The examples field is mutually exclusive of the example field. Furthermore, if referencing a schema which contains an example, the examples value SHALL override the example provided by the schema.

[hkosova]

@keenle support for OAS3 media type examples is being tracked in #2651.

[shockey]

Closing as a duplicate of #2651