Example

[shockey]

Description

This PR:

• tightens parameter example functionality to be OpenAPI 3-only
• adds consistent support for media type, schema, and property level example values
• softens the aggressiveness of calling ParameterRow's onChange handler

Motivation and Context

Fixes #3437 - though that ticket mentions examples, which is not covered here, that item will live on in #2651.

How Has This Been Tested?

Many e2e tests were added:

  feature: `example` field support
    Swagger 2
      primitive parameters
        ✓ should respect a primitive x-example value (4918ms)
        ✓ should ignore a primitive example value (1493ms)
      object parameters
        ✓ should correctly consider property-level schema examples (929ms)
        ✓ should correctly consider root schema-level schema examples (867ms)
        ✓ should correctly consider nested schema-level schema examples (817ms)
      responses
        ✓ should correctly consider schema-level examples (814ms)
        ✓ should correctly consider property-level examples (813ms)
    OpenAPI 3.0
      parameters
        ✓ should respect a primitive example value (947ms)
      request bodies
        ✓ should correctly consider media type-level examples (870ms)
        ✓ should correctly consider schema-level examples (870ms)
        ✓ should correctly consider property-level examples (909ms)
      responses
        ✓ should correctly consider media type-level examples (815ms)
        ✓ should correctly consider schema-level examples (847ms)
        ✓ should correctly consider property-level examples (821ms)

Screenshots (if appropriate):

Checklist

My PR contains...

• No code changes (src/ is unmodified: changes to documentation, CI, metadata, etc.)
• Dependency changes (any modification to dependencies in package.json)
• Bug fixes (non-breaking change which fixes an issue)
• Improvements (misc. changes to existing features)
• Features (non-breaking change which adds functionality)

My changes...

• are breaking changes to a public API (config options, System API, major UI change, etc).
• are breaking changes to a private API (Redux, component props, utility functions, etc.).
• are breaking changes to a developer API (npm script behavior changes, new dev system dependencies, etc).
• are not breaking changes.

Documentation

• My changes do not require a change to the project documentation.
• My changes require a change to the project documentation.
• If yes to above: I have updated the documentation accordingly.

Automated tests

• My changes can not or do not need to be tested.
• My changes can and should be tested by unit and/or integration tests.
• If yes to above: I have added tests to cover my changes.
• If yes to above: I have taken care to cover edge cases in my tests.
• All new and existing tests passed.

[Raptor399]

Working local examples are great to have!
However, this fix does not take into account $ref examples properly.
Try this for example:

info:
  version: 0.0.0
  title: test

paths:
  /something:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
            example:
              $ref: '#/components/examples/RequestBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              example:
                $ref: '#/components/examples/ResponseBody'
components:
  schemas:
    Message:
      type: object
      properties:
        message:
          type: string
          example: Message schema example
  examples:
    RequestBody:
      value:
        message: RequestBody example
    ResponseBody:
      value:
        message: ResponseBody example

The response 200 example will be rendered as:

{
  "value": {
    "message": "ResponseBody example"
  },
  "$$ref": "#/components/examples/ResponseBody"
}

[shockey]

Hi @Raptor399!

example fields don't allow Reference Objects, so I don't think $ref support is relevant here.

Note that only examples fields are actually Example Objects.

This is based on my reading of the OpenAPI Specification - let me know if you disagree.

[dafnalia]

@shockey, so if I understand correctly the use of $ref - mentioned at the end of the Adding Examples documentation - should be covered in #2651? CC @Raptor399

[shockey]

@dafnalia, correct!

[KaiserCoaster]

example fields don't allow Reference Objects, so I don't think $ref support is relevant here.

Note that only examples fields are actually Example Objects.

This is based on my reading of the OpenAPI Specification - let me know if you disagree.

@shockey, I understand that examples support is still in the works. Does that also refer to the reusable examples within components?
The OpenApi spec seems a little vague around this area - can I only $ref a reusable example component by using the examples field, or should I be able to do that within example too?
I'm not sure if I'm not following OpenApi correctly, or if SwaggerUI doesn't support this yet, or if this is an issue with SwaggerUI.

Example of what I'm trying to do:

components:
  examples:
    ValidationError: # Note that I also tried putting the fields below inside a value field, but that seems to work even less in the UI.
      status: 400
      message: Validation error occurred

paths:
  /someEndpoint:
    post:
      ...
      responses:
        '400':
          content:
            application/json:
              ...
              example:
                $ref: '#/components/examples/ValidationError'

The only uses of reusable examples I see in the spec is within examples fields, none within just example

examples:
  confirmation-success:
    $ref: '#/components/examples/confirmation-success'

Thanks!

[shockey]

@KaiserCoaster you're reading it correctly - $ref within an example is not allowed.

I understand that examples support is still in the works. Does that also refer to the reusable examples within components?

Yes - the current state of things is that we don't handle Response.content.{mediaType}.examples (or MediaType.examples in general) at the moment. Because Response.content.{mediaType}.examples is the only way to consume reusable component examples, you can't do anything with them in Swagger UI today.

This will change soon, see #2651 (comment)!