Skip to main content

Added Support for Export of $ref Sibling Data in OpenAPI Using allOf

· 2 min read

APIMatic now exports any data available for a schema that also uses $ref to reference another schema definition, by placing the reference and the sibling data within the allOf construct.

Details​

OpenAPI (v2.0, v3.0) supports the keyword $ref to reference pre-defined components without needing to define them again in the API specification document. It, however, does not allow any sibling properties to be included directly next to $ref like description, example, etc. The following is, therefore, invalid:

  properties:
    pet:
      $ref: '#/components/schemas/Pet'
      description: Describes a pet.

For such cases, wrapping schema information in allOf is recommended instead. APIMatic export feature will now also use allOf to export schema definitions that use $ref and also contain additional information like example, description, xml attributes, etc. e.g. the above case will now be exported as:

  properties:
    pet:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - description: Describes a pet.

If the schema definition contains $ref but does not contain any sibling data that requires to be added, then the schema definition is exported as before:

  properties:
    pet:
      $ref: '#/components/schemas/Pet'

How to Avoid Changes to Output?​

If you wish to avoid these changes, you can configure the export process as described here and set the export setting AddRefSiblingDataInAllOfSchema to false.