Using discriminator

In certain scenarios, a single object may have multiple structural forms. For example, a book can be either an eBook or a paperback. In such cases, the discriminator field can be used to distinguish between different Schema types.

The discriminator is usually used in combination with oneOf or anyOf to indicate that "the value of a specific field determines the concrete type of the object".

propertyName: Specifies the field name used to differentiate types.

mapping: Defines the mapping between field values and the corresponding Schemas.

Configuring in Apidog

Method 1: Using JSON Schema

Configure oneOf via Visual Interface

Open the request or response editor of the API. Select the field you want to define as a "Schema Composition" field. Click Advanced Settings → Schema Composition → oneOf, and reference the schema you want to combine in oneOf, such as eBook and Paperback.

Add discriminator via JSON Schema

Click JSON Schema in the editor to switch to code mode.

Add the discriminator configuration, for example:

Replace 10331225 and 10331226 with the IDs of your actual schema. You can see these IDs when opening the JSON Schema configuration panel.

Verify the Result

After saving, Apidog will automatically recognize different types based on the type field. When you Publish Docs, the API documentation will correctly display the differentiated types.

Method 2: Importing OpenAPI File

Write the definition into an OpenAPI YAML or JSON file, for example:

Full definition example:

Then, in Apidog, choose Import OpenAPI File.

After importing, Apidog will automatically recognize the discriminator and correctly map types in schema and endpoint definitions. When you Publish Docs, the API documentation will correctly display the differentiated types.

Configuring in Apidog#

Method 1: Using JSON Schema#

Method 2: Importing OpenAPI File#

Configuring in Apidog

Method 1: Using JSON Schema

Method 2: Importing OpenAPI File