Support Added for OpenAPI v3 Discriminator Mapping Information

The Discriminator object in OpenAPI v3 supports a set of mapping values that helps determine which schema to map to based on the discriminator property's value in the payload. We have now added support for this set of mapping values in our OpenAPI v3 import and export. Previously, only the key or title of each schema involved in the hierarchy was considered as its discriminator value or one provided using the x-discriminator-value extension.

Details

The information in the Discriminator object mapping values will now be mapped to the Discriminator Value of each Model in APIMatic that is involved in the hierarchy.

components:
  schemas:
    Pet:
      type: object
      required:
      - pet_type
      properties:
        pet_type:
          type: string
      discriminator:
        propertyName: pet_type
        mapping:
          cachorro: Dog
    Cat:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Cat`
        properties:
          name:
            type: string
    Dog:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Dog`
        properties:
          bark:
            type: string

In the example above, the model Dog will have a discriminator value of cachorro as specified in the mapping values of model Pet. Whereas, the model Cat will have a discriminator value of Cat since it has no mapping information available and, therefore, the schema's name is picked up as its discriminator value.

Impact

• If you've been using Discriminator mapping in your OpenAPI v3 file, re-importing it can replace the existing Discriminator values of your models with the ones specified in the mapping defined. This can impact your SDK generation, portal generation as well as transformations. To disable this, you can upload a Metadata file along with your OpenAPI specification in the form of a ZIP file. This metadata file should set the ImportFromOpenApiDiscriminatorMapping import setting as false. Alternatively, you should remove the mapping information from your API specification to avoid issues.

• If your API has discriminator values set for models, exporting such APIs to OpenAPI v3 will also export mapping information. To disable this, you will have to first re-import your API specification along with a Metadata file in a ZIP file. This metadata file should set the ExportDiscriminatorMappingValues export setting as false. Exporting this API then at any later time will not export the mapping information anymore.

• If you've been using the x-discriminator-value extension to specify the Discriminator value for your model, it will make more precedence than the information available in the discriminator mapping definition.