Parâmetros de API frequentemente possuem estruturas complexas, com um único endpoint suportando múltiplas combinações diferentes de parâmetros. Por exemplo, um endpoint de login pode suportar autenticação por nome de usuário e senha, autenticação por e-mail e senha, ou códigos de verificação por número de telefone. Endpoints de pagamento podem oferecer vários métodos como cartões de crédito, WeChat Pay ou Alipay, cada um exigindo campos diferentes.
Abordagens tradicionais de documentação de API frequentemente apenas listam todos os campos possíveis e usam descrições de texto como "escolha campos diferentes com base em cenários diferentes". Essa abordagem não é precisa nem amigável ao desenvolvedor, muitas vezes levando à confusão. Apidog suporta os recursos oneOf, anyOf e allOf do JSON Schema, permitindo que você descreva com precisão essas estruturas de dados compostas complexas em sua documentação de API.
Compreendendo os Três Modos de Combinação
No JSON Schema, oneOf, anyOf e allOf são usados para combinar múltiplos sub-schemas, mas eles possuem significados lógicos diferentes:
- allOf: Combina múltiplas regras, exigindo que todas correspondam
- anyOf: Pelo menos uma correspondência é necessária, múltiplas correspondências são aceitáveis
- oneOf: Deve corresponder a exatamente um esquema, corresponder a zero ou múltiplos esquemas falhará
Configurando Modos de Combinação no Apidog
Apidog oferece duas maneiras de usar esses modos de combinação:
Abordagem do Editor Visual
O primeiro método usa o painel de edição visual. No seu projeto, clique em "Modelos de Dados" para criar um novo modelo, então encontre "Modos de Combinação" na seleção de tipo. Escolha o modo oneOf, anyOf ou allOf necessário, então defina estruturas de dados específicas para cada sub-schema.
Editor de Código JSON Schema
A segunda abordagem envolve a edição direta do código JSON Schema. No painel de edição do modelo de dados, você pode alternar para o modo de código e escrever JSON Schema diretamente para definir esses padrões de combinação lógica. Este método é mais direto para desenvolvedores familiarizados com JSON Schema.
Aplicando Esses Padrões em Endpoints de API
Uma vez que você definiu seus modelos de dados, você pode usá-los em sua documentação de API. Ao editar parâmetros de requisição de interface, selecione o tipo Body como JSON, então na seção de estrutura de dados, você pode referenciar os "Modelos de Dados" que acabou de criar, ou selecionar diretamente "Modos de Combinação" para definir estruturas de parâmetros complexas.
O mesmo princípio se aplica às definições de dados de resposta. Ao adicionar exemplos de resposta na seção de resposta de retorno, você pode usar modos de combinação para descrever formatos de resposta para diferentes cenários. Dessa forma, os desenvolvedores podem entender claramente qual estrutura de dados será retornada em diferentes situações.
Casos de Uso do Mundo Real
allOf: Combinando Múltiplas Estruturas
allOf combina múltiplas estruturas juntas - não se trata de seleção, mas de empilhamento. allOf não altera a hierarquia dos campos; todos os campos acabam no mesmo objeto. Ele simplesmente empilha múltiplas regras sobre os mesmos dados. Pense nisso como "E lógico" - todas as restrições da subestrutura devem ser satisfeitas.
Por exemplo, este JSON Schema:
{
"allOf": [
{
"description": "Informações básicas do usuário",
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" }
},
"required": ["id", "name"]
},
{
"description": "Informações de contato",
"type": "object",
"properties": {
"email": { "type": "string", "format": "email" },
"phone": { "type": "string" }
},
"required": ["email"]
}
]
}
Este esquema significa: os dados finais devem satisfazer simultaneamente as estruturas de "informações básicas do usuário" e "informações de contato".
Em outras palavras, o corpo da requisição deve incluir id, name e email, enquanto phone é opcional.
Dados válidos:
{
"id": 1001,
"name": "John Doe",
"email": "john@example.com",
"phone": "1-800-000-0000"
}
Dados inválidos:
{
"id": 1001,
"name": "John Doe"
}
Isso não possui o campo de e-mail obrigatório e não satisfaz a segunda estrutura.
Essa abordagem é adequada para dividir objetos complexos. Informações do usuário, detalhes do pedido, itens de configuração, etc., podem ser divididos em estruturas independentes por módulos funcionais, e então combinados usando allOf. Outras interfaces que precisam de parte dessas estruturas podem referenciá-las diretamente sem definições redundantes.
anyOf: Satisfazendo Pelo Menos Uma Condição
anyOf lista múltiplas estruturas possíveis, e os dados são considerados válidos desde que estejam em conformidade com pelo menos uma delas. Não importa se múltiplas condições são satisfeitas, nem exige uma correspondência única.
Por exemplo, um campo de identificador pode ser um e-mail ou um número de telefone. Esses dois formatos são distintamente diferentes, mas ambos pertencem à categoria de "credenciais de login do usuário".
Você pode usar anyOf para expressar claramente essa intenção de "pode ser A ou B":
{
"type": "object",
"properties": {
"identifier": {
"description": "Identificador do usuário: pode ser e-mail ou número de telefone",
"anyOf": [
{
"title": "Formato de E-mail",
"description": "Deve ser um endereço de e-mail válido",
"type": "string",
"format": "email"
},
{
"title": "Formato de Telefone",
"description": "Deve ser um número de telefone internacional válido",
"type": "string",
"pattern": "^\\+?[1-9]\\d{1,14}$"
}
]
},
"password": {
"type": "string",
"minLength": 6,
"description": "Senha de login, mínimo de 6 caracteres"
}
},
"required": ["identifier", "password"],
"description": "Parâmetros de requisição de login do usuário"
}
Esta estrutura significa: o identificador é uma string que é considerada válida desde que satisfaça o formato de e-mail ou o formato de número de telefone.
Dados válidos:
{
"identifier": "test@example.com",
"password": "123456"
}
{
"identifier": "+1-800-000-0000",
"password": "123456"
}
Dados inválidos:
{
"identifier": "abc",
"password": "123456"
}
"abc" não é nem um e-mail nem um formato de número de telefone válido, não satisfazendo nenhuma das condições.
oneOf: Escolha Exatamente Uma Opção
oneOf lista múltiplas estruturas possíveis, e os dados devem estar em conformidade com exatamente uma delas. Ele enfatiza a exclusividade - você só pode escolher uma, nem mais, nem menos.
Por exemplo, métodos de pagamento: para completar um pagamento, os usuários devem escolher um entre cartão de crédito, WeChat Pay ou Alipay, mas não podem usar dois métodos simultaneamente, nem podem escolher nenhum. Você pode definir essa lógica de "escolha única" usando oneOf:
{
"properties": {
"paymentMethod": {
"description": "Método de pagamento, deve escolher exatamente um",
"oneOf": [
{
"title": "Pagamento com Cartão de Crédito",
"description": "Pagar com cartão de crédito, requer número do cartão e data de validade",
"type": "object",
"properties": {
"type": { "const": "credit_card" },
"cardNumber": { "type": "string" },
"expiryDate": { "type": "string" }
},
"required": ["type", "cardNumber", "expiryDate"],
"additionalProperties": false
},
{
"title": "Pagamento WeChat",
"description": "Pagar via WeChat, requer o openid do usuário",
"type": "object",
"properties": {
"type": { "const": "wechat" },
"openid": { "type": "string" }
},
"required": ["type", "openid"],
"additionalProperties": false
},
{
"title": "Pagamento Alipay",
"description": "Pagar via Alipay, requer ID da conta",
"type": "object",
"properties": {
"type": { "const": "alipay" },
"accountId": { "type": "string" }
},
"required": ["type", "accountId"],
"additionalProperties": false
}
]
}
}
}
Esta definição significa: paymentMethod é um objeto que só pode corresponder a uma das três subestruturas.
Exemplos válidos:
{
"paymentMethod": {
"type": "wechat",
"openid": "wx_123456"
}
}
{
"paymentMethod": {
"type": "credit_card",
"cardNumber": "4111111111111111",
"expiryDate": "12/25"
}
}
Exemplo inválido:
{
"paymentMethod": {
"type": "wechat",
"openid": "wx_123",
"accountId": "2088102"
}
}
Embora o tipo seja "wechat", a presença de accountId pode fazer com que ele corresponda a múltiplas estruturas, fazendo com que oneOf falhe. Adicionar "additionalProperties": false previne essa confusão (significando que nenhum campo adicional é permitido), garantindo que cada estrutura permita apenas seus próprios campos definidos. Apidog suporta configuração visual para additionalProperties.
Quando você precisa fazer escolhas exclusivas entre múltiplos tipos distintos, oneOf é a maneira mais direta e confiável de expressar isso.
Escolhendo o Modo de Combinação Correto
A escolha do modo de combinação depende principalmente da sua lógica de negócio:
- Use allOf quando precisar combinar e herdar múltiplos padrões
- Use anyOf quando precisar de combinações opcionais flexíveis
- Use oneOf quando precisar de escolhas exclusivas estritas
Compreender seus respectivos papéis permite que sua documentação de API descreva com precisão estruturas de dados complexas, tornando imediatamente claro para os usuários da interface como passar parâmetros.
Conclusão
O suporte abrangente do Apidog ao JSON Schema capacita os desenvolvedores a criar documentação de API precisa e clara, mesmo para as estruturas de parâmetros mais complexas. Ao alavancar as combinações oneOf, anyOf e allOf, você pode eliminar a ambiguidade e fornecer orientação cristalina aos consumidores da API.
Pronto para experimentar o poder da documentação de API avançada? Experimente o Apidog hoje e veja como se torna fácil gerenciar parâmetros de API complexos com precisão e clareza.