Introducing Support for Accepting Unlisted Enum Properties

We have introduced the acceptance of unlisted enum values in the API response in SDKs for all languages.

Details

Enums are typically used to define collections of constants that are related in some context. They allow developers to work with these values in a more meaningful and structured manner. Within OpenAPI, an enum can be defined as follows:

components:
  schemas:
    Days:
       type: string
       enum:
         - Monday
         - Tuesday
         - Wednesday

Occasionally, API definitions may evolve, adding new values such as Thursday and Friday to an existing enum. These frequent updates in the API specifications will lead to the incompatibility between client and server side implementaions.

Previously, our auto generated SDKs were also facing the same challenge and any older versions of generated SDKs would not permit additional values in enums. Consequently, such SDKs risked crashing the wrapping application when encountering these new values in server responses.

What's New?

With our latest update, you can now configure enums to accommodate potential future additions, ensuring seamless integration with applications by enabling the x-allow-additional-enum-items extension, which is disabled by default. For example:

components:
  schemas:
    Days:
      type: string
      enum:
        - Monday
        - Tuesday
        - Wednesday
      x-allow-additional-enum-items: true

note

This feature exclusively enables the acceptance of additional enum items in API responses but does not provide the capability to send unlisted enum properties in API requests.

To apply the configuration globally in the API definition, you can enable the import setting AllowAdditionalEnumItems, which is disabled by default in APIMATIC-META.json as following:

{
    "ImportSettings": {
        "AllowAdditionalEnumItems": true
    }
}