Tutorial sobre OneOf, anyOf, allOf
Dentro desse contexto, as palavras-chave oneOf, anyOf e allOf surgem como ferramentas poderosas para construir APIs flexíveis e adaptáveis. oneOf ajuda a especificar múltiplos esquemas válidos para uma única estrutura de dados.
Crear APIs que se integren de manera fluida con estructuras de dados em evolução é crucial no desenvolvimento de API. JSON Schema, um padrão amplamente adotado para definição de API, fornece uma estrutura robusta para a definição de estruturas de dados e regras de validação em combinação com OpenAPI.
Dentro deste framework, as palavras-chave oneOf, anyOf e allOf surgem como ferramentas poderosas para construir APIs flexíveis e adaptáveis. oneOf ajuda a especificar múltiplos esquemas válidos para uma única estrutura de dados.
anyOf fornece um mecanismo para validar uma estrutura de dados contra outros esquemas disponíveis. allOf combina várias opções de esquema em uma única regra de validação, garantindo que uma estrutura de dados atenda a todas as restrições especificadas. Apidog ajuda as APIs a se adaptarem sem esforço às diversas necessidades de dados.
O que é oneOf
O termo "oneOf" refere-se a uma construção ou palavra-chave usada no contexto de definições de esquema como esquemas JSON. "oneOf" permite especificar múltiplos subschemas, e uma instância válida do esquema deve aderir às restrições de exatamente um desses subschemas. Por exemplo, considere um esquema JSON para uma pessoa, onde uma pessoa pode ser um adulto ou uma criança.
A palavra-chave "oneOf" poderia especificar dois subschemas, um para adultos e um para crianças. O documento sendo validado deve satisfazer as restrições do esquema adulto ou do esquema infantil, mas não ambos. Aqui está como ficaria em um esquema JSON.
{
"type": "object",
"oneOf": [
{
"properties": {
"age": { "type": "integer", "minimum": 18 }
},
"required": ["age"]
},
{
"properties": {
"age": { "type": "integer", "maximum": 17 }
},
"required": ["age"]
}
]
}
Neste exemplo, a palavra-chave "oneOf" é usada para definir dois subschemas: um para adultos e um para crianças. O documento sendo validado deve satisfazer as restrições do esquema adulto ou do esquema infantil, mas não ambos. A propriedade "age" é um discriminador para determinar qual subschema deve ser aplicado.
Essa flexibilidade é benéfica quando você tem estruturas válidas diversas para um documento JSON com base em diferentes condições. A palavra-chave "oneOf" garante exclusividade mútua entre os subschemas definidos, garantindo que uma instância válida se conforme a apenas uma das estruturas especificadas. Essa capacidade torna "oneOf" uma ferramenta valiosa para descrever com precisão modelos de dados complexos e manter a integridade dos dados em vários cenários.
O que é anyOf
A palavra-chave "anyOf" é outra construção para definir um esquema onde a instância validada deve conformar-se a pelo menos um subschema especificado. Ao contrário de "oneOf", que impõe adesão exclusiva a um subschema, "anyOf" oferece mais flexibilidade ao permitir que a instância satisfaça as restrições de pelo menos um dos subschemas especificados.
Vamos considerar um cenário prático onde "anyOf" pode ser benéfico. Imagine trabalhar com dados JSON representando indivíduos, alguns adultos e outros estudantes. Tanto adultos quanto estudantes têm propriedades distintas, e você quer criar um esquema que acomode ambos os casos.
A palavra-chave "anyOf" permite que você expresse essa flexibilidade, permitindo que o documento JSON seja válido se ele se conformar ao esquema para adultos ou estudantes. Aqui está como este exemplo é representado em um esquema JSON.
{
"type": "object",
"anyOf": [
{
"properties": {
"name": { "type": "string" },
"age": { "type": "integer", "minimum": 18 }
},
"required": ["name", "age"]
},
{
"properties": {
"name": { "type": "string" },
"grade": { "type": "string", "enum": ["A", "B", "C"] }
},
"required": ["name", "grade"]
}
]
}
Neste exemplo, a palavra-chave "anyOf" é usada para definir dois subschemas: um para adultos e um para estudantes. O documento JSON é considerado válido se satisfizer as restrições do esquema adulto ou do esquema estudantil. Isso permite uma representação flexível de estruturas de dados diversas dentro do mesmo esquema abrangente, tornando "anyOf" uma ferramenta poderosa para lidar com cenários de dados variados.
OneOf vs anyOf: Qual é a diferença no esquema z
No Z Schema, OneOf e AnyOf são usados para definir múltiplos esquemas, mas servem propósitos diferentes.
OneOf:
OneOf é usado quando exatamente um dos esquemas definidos deve corresponder.
Isso garante que os dados validem contra apenas um dos esquemas especificados.
Exemplo:
{
"OneOf": [
{"type": "string"},
{"type": "number"}
]
}
Este esquema garante que os dados sejam uma string ou um número, mas não ambos.
AnyOf:
AnyOf é usado quando qualquer um ou mais dos esquemas definidos pode corresponder.
Isso permite que os dados validem contra múltiplos esquemas especificados.
Exemplo:
{
"AnyOf": [
{"type": "string"},
{"type": "number"}
]
}
O que é allOf
A palavra-chave "allOf" no JSON Schema define um esquema onde a instância validada deve conformar-se a todos os subschemas especificados. Essencialmente, representa uma operação lógica AND para os subschemas. Isso significa que o documento JSON validado deve satisfazer as restrições de cada subschema listado sob "allOf". Aqui está um exemplo:
{
"allOf": [
{
"properties": {
"name": { "type": "string" },
"age": { "type": "integer", "minimum": 18 }
},
"required": ["name", "age"]
},
{
"properties": {
"hasDegree": { "type": "boolean", "default": true }
},
"required": ["hasDegree"]
}
]
}
Neste exemplo, a palavra-chave "allOf" combina dois subschemas. O primeiro subschema define propriedades para adultos, incluindo um nome e idade com restrições específicas. O segundo subschema introduz uma propriedade para indivíduos com um diploma, neste caso, uma propriedade boolean "hasDegree" com um valor padrão de true. O efeito combinado de "allOf" é que o documento JSON validado deve aderir a ambas as restrições. Ele deve ter um nome, idade (satisfazendo o primeiro subschema), e também incluir a propriedade "hasDegree" (satisfazendo o segundo subschema).
A palavra-chave "allOf" é útil ao criar um esquema que abrange as propriedades e restrições de múltiplos subschemas, garantindo que a instância validada atenda a todas as condições especificadas. Essa operação lógica AND difere de "anyOf" e "oneOf", permitindo flexibilidade em satisfazer pelo menos um ou exatamente um dos subschemas especificados.
O que é Apidog?
Apidog é uma plataforma versátil de integração de API que simplifica testes, depuração, design, simulação e documentação de API. Oferece uma interface amigável, ferramentas colaborativas e recursos para avaliações completas de API.
Apidog se destaca na documentação de respostas de API com layouts personalizáveis e facilita esforços colaborativos dentro das equipes. Suas ferramentas de teste permitem a adição de asserções visuais e a criação de ramos de teste. A plataforma também ajuda a monitorar a atividade da API e fornece capacidades de simulação eficientes, eliminando a necessidade de scripts durante o desenvolvimento.
Esquemas JSON Apidog com oneOf, anyOf e allOf
Agora que você sabe o que são esquemas JSON e como eles utilizam oneOf, anyOf e allOf em sua estrutura, vamos defini-los no Apidog. Para criar esses esquemas de forma eficiente no Apidog, certifique-se de ter o Apidog baixado em seu sistema ou ter uma conta para usar os serviços do Apidog online.
Como Criar OneOf
- Crie um novo projeto no Apidog com tipo HTTP.
2. Crie um novo Esquema clicando no botão novo Esquema.
3. Clique na opção Gerar a partir do JSON e vá para a opção esquema JSON.
4. Insira o seguinte código no editor.
{
"title": "Exemplo de Esquema de Pagamento",
"type": "object",
"properties": {
"payment": {
"oneOf": [
{
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"currency": {
"type": "string"
}
},
"required": ["amount", "currency"]
},
{
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"currency": {
"type": "string"
},
"cardDetails": {
"type": "object",
"properties": {
"cardNumber": {
"type": "string"
},
"expirationDate": {
"type": "string"
},
"cvv": {
"type": "string"
}
},
"required": ["cardNumber", "expirationDate", "cvv"]
}
},
"required": ["amount", "currency", "cardDetails"]
}
]
}
},
"required": ["payment"]
}
5. Salve seu esquema.
Seu esquema oneOf foi criado com sucesso!
Como Criar anyOf
Siga todos os passos acima para oneOf, mas a única alteração que você fará para o seu esquema anyOf é mudar o código. Insira o seguinte código no editor para criar seu esquema.
{
"type": "object",
"properties": {
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"zip": {
"type": "string"
}
},
"required": ["street", "city", "state", "zip"]
},
{
"type": "object",
"properties": {
"country": {
"type": "string"
}
},
"required": ["country"]
}
]
}
},
"required": ["address"]
}
allOf
Siga todos os passos acima para oneOf, mas a única mudança que você fará para o seu esquema allOf é mudar o código. Insira o seguinte código no editor para criar seu esquema.
{
"type": "object",
"properties": {
"product": {
"allOf": [
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": ["name", "description"]
},
{
"type": "object",
"properties": {
"price": {
"type": "number"
},
"stock": {
"type": "integer"
}
},
"required": ["price", "stock"]
}
]
}
},
"required": ["product"]
}
Benefícios de criar esquemas com Apidog
Você pode fazer várias coisas úteis agora que criou seus esquemas JSON com Apidog. Alguns dos benefícios são mencionados abaixo.
Documentação da API
Você pode integrar seu Esquema JSON na sua documentação da API para fornecer descrições claras e abrangentes das estruturas de dados e regras de validação dos seus endpoints de API. Isso melhora a compreensão do desenvolvedor e reduz o risco de erros no uso da API.
Geração de código
Você pode utilizar ferramentas como as capacidades de geração de código do Apidog para gerar automaticamente bibliotecas de cliente e código do lado do servidor a partir do seu Esquema JSON. Isso agiliza o processo de desenvolvimento e garante consistência entre a definição da sua API e sua implementação.
Validação de dados e tratamento de erros
Você pode utilizar bibliotecas de validação de Esquema JSON para validar requisições e respostas de API recebidas, garantindo que os dados conformem à estrutura e restrições definidas. Isso ajuda a evitar que dados inválidos entrem no seu sistema e reduz o risco de erros de aplicação.
Teste de API
Você pode aproveitar o Esquema JSON para gerar casos de teste para seus endpoints de API e criar servidores simulados para teste. Isso facilita um teste abrangente de API e garante que sua API funcione conforme o esperado.
Design de API
Você pode continuar refinando seu Esquema JSON à medida que sua API evolui para acomodar novas necessidades de dados e padrões de uso. Isso garante que sua API permaneça flexível e adaptável às demandas em mudança.
Conclusão
Em conclusão, integrar esquemas JSON com Apidog pode aprimorar significativamente o processo de documentação de APIs. O JSON Schema fornece uma maneira padronizada de descrever a estrutura e as restrições dos dados JSON, e quando integrado com ferramentas de documentação de API, garante que a documentação reflita com precisão os formatos de requisição e resposta esperados.
Apidog suporta recursos que aproveitam os esquemas JSON. Por exemplo, pode gerar automaticamente documentação com base nos esquemas definidos, facilitando a atualização da documentação à medida que a API evolui.
