Support dropdown for discriminator

[YousefHaggy]

Fixes #2438 and adds a dropdown to select between schemas that extend a base schema via allOf with discriminator

Sample spec:
spec.json

Description

• When parsing the spec, build a map of parent to child schemas
• In ModelWrapper, if the current schema has child schemas, render a drop down to select from those schemas
• Supports both explicit and implicit mappings

Motivation and Context

OpenAPI spec supports inheritance via allOf and discriminator, but currently in Swagger UI when you reference a schema that is extended with allOf, there's no indication of this inheritance and valid child schemas a user can input. Provides a poor user experience for specs that rely on this kind of structure

This works in other tools like Redoc: https://github.com/Rebilly/ReDoc/blob/master/docs/images/discriminator-demo.gif

Fixes #2438. Solves a very common allOf usecase, some examples in the OAS 3.1.1 official spec

How Has This Been Tested?

I've manually tested this change using the attached sample spec. I tested for both 3.0 and 3.1. I tested a spec with no explicit mappings, all explicit mappings, and a mix

spec.json

Ran all existing unit tests successfully. Tried to run npm run e2e as the README.md says, but no script e2e exists

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.

[YousefHaggy]

Is there a better way to get specAction down to model-wrapper.jsx than plumbing it down everywhere like this? I couldn't find a context provider with specActions in the hierarchy

[YousefHaggy]

for OAS 3.0.X, the model is inline with the dropdown if we don't specify this

[YousefHaggy]

@char0n Could I get you or another maintainers review on this? Thanks!

[ponelat]

Hi @YousefHaggy thank you for taking the time to create this. I think it would be great to get a selector to change between discriminator types. There are a bunch of edge-cases to consider, including discriminator resolving which hasn't been addressed. It's something new that popped up with 3.0.4/3.1.1 versions of OpenAPI Specification.

We will take a look when we can to help move this forward, thanks for your patience here!

[YousefHaggy]

@ponelat Thanks for your reply. I'm happy to work on testing and addressing the edge cases associated with discriminator. Wanted to see if this selector idea had traction before jumping down the rabbit hole :)

While this PR doesn't factor in the edge cases, it does address imo the most popular and common manifestation of allOf / discriminator polymorphism. It addresses the example provided in the Github issue as well as some examples in the OAS 3.1.1 official spec

What do you think about exposing this current fix behind a configuration parameter, experimentalDiscriminatorSelector? So that some kind of solution exists for people with the common use case who have been waiting quite some time. If not, perhaps some way to expose it easily as a plugin?

[glowcloud]

Hi @YousefHaggy,

Thank you for your contribution.

We’ve decided to close this PR, as we will be handling the processing of the discriminator in ApiDOM with proper dereferencing and normalization. We are currently working on a proof of concept to handle it there.