oneOf, allOf, anyOf

oneOf, anyOf e allOf são palavras-chave na especificação JSON Schema utilizadas para definir estruturas de dados compostas. São, essencialmente, operadores lógicos aplicados à validação de dados. O Apidog suporta totalmente estas funcionalidades do JSON Schema, ajudando-o a criar documentação de API e regras de validação de dados mais precisas.

Conceitos Básicos

allOf

allOf significa que os dados devem satisfazer simultaneamente todas as condições dos subesquemas, equivalente à operação AND em operações lógicas. Tal como a expressão "tanto... como..." na linguagem quotidiana, todas as condições devem ser cumpridas simultaneamente para que a validação seja aprovada.

anyOf

oneOf

Tabela de Comparação Lógica

Palavra-chave	Operação Lógica	Requisito da Condição	Caso de Utilização Típico
`allOf`	AND	Deve satisfazer todas as condições simultaneamente	Herança, extensão
`anyOf`	OR	Deve satisfazer pelo menos uma condição	Combinações opcionais
`oneOf`	XOR	Deve satisfazer exatamente uma condição	Escolhas mutuamente exclusivas

Utilização no Apidog

1. Utilizar o Editor Visual

Passo 1: Criar Esquemas de Dados

No seu projeto, clique em "Schemas" e, em seguida, em "New Schema".

Passo 2: Adicionar Composição de Esquemas

No painel de edição do esquema de dados, ao selecionar o tipo, clique em "Schema Composition" e escolha oneOf, anyOf ou allOf. Defina estruturas de dados específicas para cada subesquema.

2. Utilizar o Editor de Código JSON Schema

Também pode editar diretamente o código JSON Schema no painel de edição do esquema de dados para definir estes padrões de composição lógica.

Aplicação na Documentação da API

Definição de Parâmetros do Pedido

Ao definir parâmetros de pedido de endpoint, pode utilizar estes padrões de composição para descrever estruturas de parâmetros complexas:

Aceda à página de edição da API.

Na secção "Request Parameters", selecione Body e escolha o tipo JSON.

Na estrutura de dados, clique em "Reference Schema", ou selecione a "Schema Composition" adequada com base na lógica de negócio, ou defina um JSON Schema personalizado.

Composição de esquemas de parâmetros do pedido

Definição de Dados da Resposta

Da mesma forma, pode utilizar esta composição de esquemas nos dados da resposta:

Na secção "Response", adicione exemplos de resposta.

Utilize a composição de esquemas para descrever diferentes formatos de resposta.

Exemplos de Utilização Prática

Exemplo de allOf (Operação AND)

Utilizar allOf permite-lhe combinar vários esquemas de dados, exigindo que os dados satisfaçam todas as condições simultaneamente. Isto é como dizer "as informações do utilizador devem incluir informações básicas AND informações de contacto":

{
  "allOf": [
    {
      "description": "Basic user information",
      "type": "object",
      "properties": {
        "id": { "type": "integer" },
        "name": { "type": "string" }
      },
      "required": ["id", "name"]
    },
    {
      "description": "Contact information", 
      "type": "object",
      "properties": {
        "email": { "type": "string", "format": "email" },
        "phone": { "type": "string" }
      },
      "required": ["email"]
    }
  ]
}

Resultado: Os dados finais devem conter os campos id, name e email, sendo phone opcional. Todas as restrições dos subesquemas são combinadas e executadas, conforme mostrado abaixo:

Exemplo de anyOf (Operação OR)

Utilizar anyOf fornece vários caminhos de validação opcionais — os utilizadores podem escolher um ou vários métodos. Isto é como dizer "os utilizadores podem iniciar sessão através de nome de utilizador/palavra-passe OR email/palavra-passe OR telefone/código de verificação":

{
  "type": "object",
  "properties": {
    "login": {
      "anyOf": [
        {
          "description": "Username/password login",
          "properties": {
            "username": { "type": "string" },
            "password": { "type": "string" }
          },
          "required": ["username", "password"]
        },
        {
          "description": "Email/password login",
          "properties": {
            "email": { "type": "string", "format": "email" },
            "password": { "type": "string" }
          },
          "required": ["email", "password"]
        },
        {
          "description": "Phone/verification code login",
          "properties": {
            "phone": { "type": "string" },
            "verifyCode": { "type": "string" }
          },
          "required": ["phone", "verifyCode"]
        }
      ]
    }
  }
}

Resultado: Os utilizadores podem fornecer informações para um ou vários métodos de início de sessão, desde que pelo menos um método satisfaça os requisitos de validação, conforme mostrado abaixo:

Exemplo de oneOf (Operação XOR)

Utilizar oneOf garante que os utilizadores só podem escolher um método de pagamento e não podem fornecer vários métodos simultaneamente. Isto é como dizer "o método de pagamento deve ser cartão de crédito XOR PayPal XOR transferência bancária — exatamente uma destas opções":

{
  "type": "object", 
  "properties": {
    "payment": {
      "oneOf": [
        {
          "description": "Credit card payment",
          "type": "object",
          "properties": {
            "type": { "const": "credit_card" },
            "cardNumber": { "type": "string" },
            "expiryDate": { "type": "string" }
          },
          "required": ["type", "cardNumber", "expiryDate"],
          "additionalProperties": false
        },
        {
          "description": "PayPal payment", 
          "type": "object",
          "properties": {
            "type": { "const": "paypal" },
            "email": { "type": "string", "format": "email" }
          },
          "required": ["type", "email"],
          "additionalProperties": false
        },
        {
          "description": "Bank transfer",
          "type": "object", 
          "properties": {
            "type": { "const": "bank_transfer" },
            "accountNumber": { "type": "string" },
            "routingNumber": { "type": "string" }
          },
          "required": ["type", "accountNumber", "routingNumber"],
          "additionalProperties": false
        }
      ]
    }
  }
}

Resultado: Os utilizadores devem escolher exatamente um método de pagamento — não podem fornecer vários métodos simultaneamente, nem deixar de fornecer todos, conforme mostrado abaixo:

Melhores Práticas

Ao escolher padrões de composição, clarifique primeiro a sua lógica de negócio:

Precisa de combinar/herdar vários esquemas → Utilize allOf (operação AND)

Precisa de combinações opcionais flexíveis → Utilize anyOf (operação OR)

Precisa de escolhas mutuamente exclusivas rigorosas → Utilize oneOf (operação XOR)

Conceitos Básicos#

Tabela de Comparação Lógica#

Utilização no Apidog#

1. Utilizar o Editor Visual#

2. Utilizar o Editor de Código JSON Schema#

Aplicação na Documentação da API#

Definição de Parâmetros do Pedido#

Definição de Dados da Resposta#

Exemplos de Utilização Prática#

Exemplo de allOf (Operação AND)#

Exemplo de anyOf (Operação OR)#

Exemplo de oneOf (Operação XOR)#

Melhores Práticas#