Em nosso artigo anterior "O Que Fazer Quando a API Tem Múltiplas Estruturas de Parâmetros", discutimos que, quando uma API requer diferentes estruturas de parâmetros, você pode usar oneOf, anyOf ou allOf no Apidog para defini-las.
Uma vez que você configurou as estruturas de parâmetros usando essas composições de esquema, e seus parâmetros incluem um campo que identifica o tipo de dado, você pode tornar a documentação ainda mais clara usando o recurso discriminator da especificação OpenAPI para distinguir entre os esquemas de forma mais intuitiva.
O Que é Discriminator?
No OpenAPI, o papel do discriminator é implementar o "polimorfismo" da programação orientada a objetos.
Simplificando, ele usa uma propriedade compartilhada e seu valor exclusivo para indicar claramente qual esquema específico na lista oneOf ou anyOf deve ser usado.
Por exemplo, em uma loja de animais, precisamos usar um esquema para descrever os animais de estimação. (E gatos e cachorros têm propriedades diferentes.)
O esquema para cachorros é:
{
"name": "Hotdog",
"age": 3,
"weight": 25.5,
"petType": "dog",
"breed": "Golden Retriever",
"isVaccinated": true,
"walkingSchedule": "Morning and Evening",
"favoriteToys": ["Frisbee", "Tennis Ball"],
"trainingLevel": "Intermediate"
}O esquema para gatos é:
{
"name": "Meow",
"age": 2,
"weight": 4.2,
"petType": "cat",
"isVaccinated": true,
"isIndoor": true,
"litterBoxType": "Enclosed",
"scratchingPostHeight": 120,
"favoriteSleepingSpot": "Balcony"
}Como você pode ver, embora ambos os esquemas tenham campos comuns como petType, name, age, etc., os cachorros têm campos específicos como breed, walkingSchedule, etc., enquanto os gatos têm campos específicos como isIndoor, litterBoxType, etc.
Se você usar apenas oneOf para definir esses esquemas ao projetar sua documentação de API, a documentação pode tecnicamente distinguir entre os esquemas de cachorro e gato. No entanto, a correspondência de cada tipo não é muito clara. Os leitores precisam alternar entre as duas abas de esquema para compará-los, o que se torna confuso quando há muitos parâmetros.
Ao adicionar um discriminator, a documentação mostrará um menu suspenso, onde os leitores podem escolher o valor de petType (dog ou cat). Uma vez selecionado, a página exibe automaticamente o esquema correto com os campos relevantes. Isso elimina a necessidade de comparar várias abas e torna as diferenças entre cada esquema muito mais claras.
Um discriminator é tipicamente usado em conjunto com oneOf ou anyOf. O oneOf define os esquemas de objeto possíveis, e o discriminator informa ao analisador como determinar qual esquema aplicar com base no tipo selecionado.
Isso torna objetos complexos mais claros e ajuda as ferramentas a distinguir automaticamente os tipos ao renderizar a documentação ou gerar código.
Propriedades de Configuração do discriminator
Um discriminator contém duas propriedades chave:
- propertyName: Especifica o nome do campo usado para distinguir tipos, como
petTypeno exemplo acima. - mapping: Define a relação de mapeamento entre valores de campo e esquemas específicos, como
"dog"correspondendo ao esquema de cachorro e"cat"correspondendo ao esquema de gato.
Exemplo de configuração no OpenAPI:
discriminator:
propertyName: petType
mapping:
dog: '#/components/schemas/Dog'
cat: '#/components/schemas/Cat'Configurando Discriminator no Apidog
O Apidog suporta a configuração de discriminator de duas maneiras:
- GUI + JSON Schema
- Importando as especificações OpenAPI diretamente
Método 1: GUI + JSON Schema
Primeiro, crie os esquemas no Apidog, como Dog e Cat:
Abra o endpoint onde você deseja usar esses esquemas e vá para o editor de corpo da requisição ou resposta.
Selecione o campo que você deseja definir como uma composição de esquema e escolha Configurações Avançadas → Composições de Esquema → oneOf.
Em oneOf, referencie os esquemas de que você precisa, como Dog e Cat.
Agora você definiu múltiplos esquemas possíveis através de oneOf. Em seguida, você precisa adicionar discriminator para especificar como distinguir esses esquemas. Clique em JSON Schema para alternar para o modo de código:
Adicione a configuração discriminator no local apropriado (no mesmo nível de oneOf), por exemplo:
"discriminator": {
"propertyName": "petType",
"mapping": {
"dog": "#/definitions/190704823",
"cat": "#/definitions/190704706"
}
}Os valores em mapping, como #/definitions/190704823, são IDs únicos gerados internamente pelo Apidog para os esquemas. Você pode encontrar o caminho definitions correspondente para cada esquema no painel de configuração do JSON Schema.
Após a conclusão da configuração, salve-a. Na documentação da API, você pode alternar inteligentemente os tipos de objeto com base no valor do campo petType.
Método 2: Importando as Especificações OpenAPI Diretamente
Esta é uma abordagem mais padrão, especialmente adequada para equipes acostumadas a fluxos de trabalho "design-first".
Escreva suas especificações OpenAPI com discriminator incluído e, em seguida, importe-as para o Apidog.
Por exemplo, nas especificações OpenAPI, a definição de discriminator é a seguinte:
Pet:
oneOf:
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Cat'
discriminator:
propertyName: petType
mapping:
dog: '#/components/schemas/Dog'
cat: '#/components/schemas/Cat'Esta definição declara claramente:
- Através de
oneOf, especifica que o objeto pode ser do tipoDogouCat - Através de
discriminator, especifica a determinação do tipo específico com base no valor do campopetType - Através de
mapping, especifica claramente que"dog"corresponde ao esquemaDoge"cat"corresponde ao esquemaCat.
As especificações OpenAPI completas são as seguintes:
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'Após concluir as especificações OpenAPI, use o recurso de importação no Apidog. O Apidog analisará todas as especificações, criará automaticamente os esquemas e endpoints correspondentes e reconhecerá corretamente a configuração do discriminator (enum é adicionado aqui para bloquear os valores dos parâmetros).
Perguntas Frequentes
1. Quando Usar Discriminator?
Você deve usar um discriminator apenas quando seu endpoint já incluir um campo que identifique os esquemas. No exemplo acima, o campo petType existe no design da API e é usado para diferenciar entre os tipos de animais de estimação.
O discriminator simplesmente informa às ferramentas como escolher o esquema correto com base no valor desse campo.
Se seu endpoint não incluir tal campo identificador de tipo, então um discriminator não é apropriado — usar oneOf sozinho é suficiente.
Além disso, se seu esquema for simples ou tiver apenas algumas variações, você pode não precisar de um discriminator.
2. O Discriminator Deve Ser Usado com oneOf?
Sim. Um discriminator deve ser usado em conjunto com oneOf, anyOf ou allOf. Ele não pode definir esquemas por si só — ele apenas explica como distinguir entre múltiplos esquemas possíveis.
Conclusão
discriminator é um recurso opcional na especificação OpenAPI usado para aprimorar a experiência do usuário de oneOf/anyOf/allOf.
Quando as especificações do seu endpoint já contêm campos usados para identificar tipos, você pode configurar discriminator no Apidog para tornar a documentação da API mais clara e inteligente.
Claro, se você achar a configuração trabalhosa ou o esquema for relativamente simples, você pode usar apenas a composição de esquema como oneOf.