feat(ls): docs for OpenApi 3.1.0 Discriminator object

[tim-lai]

Description

• Add documentation for OpenApi 3.1.0 Discriminator Object.

• add custom section for Additional documentation topics that provide external links for further reading.

• documentation trimmed per recommendations from ls: oas3.1 documentation for discriminator #2041 (comment)

@frantuma
possible todo: add additional context reasoning comments, per #2041 (comment)

@char0n
Related issue 1: the parent screenshot below required changing this line to include targetSpec for AsyncApi

Also another issue 2: visible in the target screenshot below, is that the current linter incorrectly states that the discriminator must be a string. However at least for OpenAPI 3.1.0, it's supposed to be an object, not a string.

Motivation and Context

Ref: #2041

How Has This Been Tested?

local.

fixture:

openapi: 3.1.0
info:
  title: deref
  version: 1.0.0
components:
  schemas:
    Pet:
      type: object
      required:
      - petType
      properties:
        petType:
          type: string
      discriminator:
        propertyName: petType
        mapping:
          dog: Dog

Screenshots (if appropriate):

parent (after fix mentioned in above description):

target:

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.

[char0n]

Related issue 1: the parent screenshot below required changing this line to include targetSpec for AsyncApi

Yes, our Schema sharing capacity is currently very limited. This will be deal with in #1814. AsyncAPI 2.x is using JSON Schema Draft 7, OpenAPI 3.0x is using Draft 4 and OpenAPI 3.1.0 is using Draft 2020-12. Currently what you can do to fight the differences of Schema Object between specifications is to use targetSpec (as you suggested). It's not ideal but that's what it currently is until #1814 is completed.

I've issued a PR that will bind current discriminator impl to AsyncAPI only and allow you to plug in what you need.

Also another issue 2: visible in the target screenshot below, is that the current linter incorrectly states that the discriminator must be a string. However at least for OpenAPI 3.1.0, it's supposed to be an object, not a string.

Yes the same issue as I described above.