In our previous article "What to Do When API Has Multiple Parameter Structures", we discussed that when an API requires different parameter structures, you can use oneOf, anyOf, or allOf in Apidog to define them.
Once you've set up the parameter structures using these schema compositions, and your parameters include a field that identifies the data type, you can make the documentation even clearer by using the discriminator feature from the OpenAPI specification to distinguish between the schemas more intuitively.
What is Discriminator?
In OpenAPI, the role of discriminator is to implement "polymorphism" from object-oriented programming.
Simply put, it uses a shared property and its unique value to clearly indicate which specific schema in the oneOf or anyOf list should be used.
For example, in a pet store, we need to use a schema to describe pets. (And cats and dogs have different properties.)
The schema for dogs is:
{
"name": "Hotdog",
"age": 3,
"weight": 25.5,
"petType": "dog",
"breed": "Golden Retriever",
"isVaccinated": true,
"walkingSchedule": "Morning and Evening",
"favoriteToys": ["Frisbee", "Tennis Ball"],
"trainingLevel": "Intermediate"
}The schema for cats is:
{
"name": "Meow",
"age": 2,
"weight": 4.2,
"petType": "cat",
"isVaccinated": true,
"isIndoor": true,
"litterBoxType": "Enclosed",
"scratchingPostHeight": 120,
"favoriteSleepingSpot": "Balcony"
}As you can see, although both schemas have common fields like petType, name, age, etc., dogs have specific fields like breed, walkingSchedule, etc., while cats have specific fields like isIndoor, litterBoxType, etc.
If you only use oneOf to define these schemas when designing your API documentation, the documentation can technically distinguish between the dog and cat schemas. However, the correspondence of each type isn't very clear. Readers must switch between the two schema tabs to compare them, which becomes confusing when there are many parameters.
By adding a discriminator, the documentation will show a dropdown menu, where readers can choose the value of petType (dog or cat ). Once selected, the page automatically displays the correct schema with the relevant fields. This removes the need to compare multiple tabs and makes the differences between each schema much clearer.
A discriminator is typically used together with oneOf or anyOf. The oneOf defines the possible object schemas, and the discriminator tells the parser how to determine which schema to apply based on the selected type.
This makes complex objects clearer and helps tools automatically distinguish types when rendering documentation or generating code.
Configuration Properties of discriminator
A discriminator contains two key properties:
- propertyName: Specifies the field name used to distinguish types, such as
petTypein the above example. - mapping: Defines the mapping relationship between field values and specific schemas, such as
"dog"corresponding to the dog schema and"cat"corresponding to the cat schema.
Configuration example in OpenAPI:
discriminator:
propertyName: petType
mapping:
dog: '#/components/schemas/Dog'
cat: '#/components/schemas/Cat'Configuring Discriminator in Apidog
Apidog supports configuring discriminator in two ways:
- GUI + JSON Schema
- Importing the OpenAPI specs directly
Method 1: GUI + JSON Schema
First, create the schemas in Apidog, such as Dog and Cat:
Open the endpoint where you want to use these schemas and go to the request or response body editor.
Select the field you want to define as a schema composition and choose Advanced Settings → Schema Compositions → oneOf.
In oneOf, reference the schemas you need, such as Dog and Cat.
Now you have defined multiple possible schemas through oneOf. Next, you need to add discriminator to specify how to distinguish these schemas. Click JSON Schema to switch to code mode:
Add the discriminator configuration at the appropriate location (at the same level as oneOf), for example:
"discriminator": {
"propertyName": "petType",
"mapping": {
"dog": "#/definitions/190704823",
"cat": "#/definitions/190704706"
}
}The values in mapping, such as #/definitions/190704823, are unique IDs generated internally by Apidog for schemas. You can find the corresponding definitions path for each schema in the JSON Schema configuration panel.
After configuration is complete, save it. In the API documentation, you can intelligently switch object types based on the value of the petType field.
Method 2: Importing the OpenAPI Specs Directly
This is a more standard approach, especially suitable for teams accustomed to "design-first" workflows.
Write your OpenAPI specs with discriminator included, then import it into Apidog.
For example, in the OpenAPI specs, the definition of discriminator is as follows:
Pet:
oneOf:
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Cat'
discriminator:
propertyName: petType
mapping:
dog: '#/components/schemas/Dog'
cat: '#/components/schemas/Cat'This definition clearly states:
- Through
oneOf, specify that the object might beDogorCattype - Through
discriminator, specify determining the specific type based on the value of thepetTypefield - Through
mapping, clearly specify that"dog"corresponds toDogschema and"cat"corresponds toCatschema.
The complete OpenAPI specs is as follows:
openapi: 3.0.3
info:
title: Pet Shop API
version: 1.0.0
components:
schemas:
Dog:
type: object
properties:
petType:
type: string
enum: [dog]
name:
type: string
age:
type: integer
weight:
type: number
breed:
type: string
isVaccinated:
type: boolean
walkingSchedule:
type: string
favoriteToys:
type: array
items:
type: string
trainingLevel:
type: string
required:
- petType
- name
- age
Cat:
type: object
properties:
petType:
type: string
enum: [cat]
name:
type: string
age:
type: integer
weight:
type: number
isVaccinated:
type: boolean
isIndoor:
type: boolean
litterBoxType:
type: string
scratchingPostHeight:
type: integer
favoriteSleepingSpot:
type: string
required:
- petType
- name
- age
Pet:
oneOf:
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Cat'
discriminator:
propertyName: petType
mapping:
dog: '#/components/schemas/Dog'
cat: '#/components/schemas/Cat'
paths:
/pets:
get:
summary: Get pet information
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'After completing the OpenAPI specs, use the import feature in Apidog. Apidog will parse all specs, automatically create corresponding schemas and endpoints, and correctly recognize the discriminator configuration (enum is added here to lock parameter values).
FAQs
1. When to Use Discriminator?
You should use a discriminator only when your endpoint already includes a field that identifies the schemas. In the example above, the petType field exists in the API design and is used to differentiate between pet types.
The discriminator simply tells tools how to choose the correct schema based on that field's value.
If your endpoint does not include such a type-identifying field, then a discriminator is not appropriate—using oneOf alone is enough.
Also, if your schema is simple or has only a few variations, you may not need a discriminator at all.
2. Must Discriminator be Used with oneOf?
Yes. A discriminator must be used together with oneOf, anyOf, or allOf. It cannot define schemas on its own—it only explains how to distinguish between multiple possible schemas.
Conclusion
discriminator is an optional feature in the OpenAPI specification used to enhance the user experience of oneOf/anyOf/allOf.
When your endpoint specs already contains fields used to identify types, you can configure discriminator in Apidog to make API documentation clearer and more intelligent.
Of course, if you find the configuration troublesome or the schema is relatively simple, you can completely use only schema composition like oneOf.
