Criar um Schema

Utilizando o Editor de Schema

O Editor de Schema é uma ferramenta poderosa que auxilia no design e na modelagem das estruturas de dados utilizadas pela sua API. Ele é baseado em JSON Schema e é utilizado para projetar estruturas de dados JSON ou XML.

Utilize o Editor de Schema para:

Desenvolver corpos de requisição e resposta de API adaptados a endpoints de API específicos.

Construir modelos de dados aplicáveis a uma ou várias APIs.

Todo schema começa com um objeto raiz. Para criar um schema, adicione propriedades a esse objeto raiz.

Criando um Schema

Adicionar Propriedades

Clique no sinal + (Adicionar um nó filho) ao lado do objeto raiz para introduzir novas propriedades.

Nomear Sua Propriedade

Insira o nome (ou chave) da propriedade.

Selecionar o Tipo da Propriedade

Escolha tipos de dados comuns ou selecione referências a schemas predefinidos.

Configurações Avançadas

Utilize o Editor de Tipo para atribuir tipos de dados, como valores padrão e formatos, a cada propriedade.

Gerenciar Propriedades

Reorganize propriedades movendo, copiando ou excluindo-as. Você também pode enriquecer propriedades com descrições e marcá-las como obrigatórias.

Métodos Alternativos

Você também pode criar novos schemas importando de tabelas de banco de dados ou arquivos JSON schema. Saiba mais sobre Gerar schemas a partir de JSON etc..

Tipo de Propriedade

Em conformidade com o padrão JSON Schema, o Editor de Schema do Apidog oferece suporte aos seguintes tipos básicos de dados:

Tipo	Descrição
null	Representa um valor JSON "null".
boolean	Representa um valor "true" ou "false", correspondente ao valor JSON "true" ou "false".
object	Representa uma coleção não ordenada de pares chave-valor, correspondente ao valor JSON "object".
array	Representa uma lista ordenada de valores, correspondente ao valor JSON "array".
number	Representa um valor numérico decimal de base 10 e precisão arbitrária, correspondente ao valor JSON "number".
string	Representa uma sequência de caracteres Unicode, correspondente ao valor JSON "string".

Tipo de Dados Array

Ao usar o tipo de dados array, uma propriedade de subnível ITEMS será gerada automaticamente. Ela especifica o tipo de dados dos elementos dentro do array.

Além das estruturas de dados padrão mencionadas anteriormente, o Editor de Schema do Apidog também oferece suporte ao seguinte:

Referenciar outros schemas: Capacidade de referenciar e reutilizar schemas definidos em outro local dentro da documentação da API.

any: Representa um valor que pode ser de qualquer tipo de dados.

Composição de Schema: Permite combinar vários schemas para criar estruturas de dados complexas.

Personalização: Permite que os usuários personalizem e adaptem o schema para atender a requisitos específicos e necessidades de modelagem de dados.

Referenciando Outros Schemas

Você pode utilizar o recurso "Referenciar outros schemas" para referenciar schemas definidos anteriormente.

Depois de referenciar outro schema, você pode visualizar o schema referenciado no Editor de Schema.

Pontos principais sobre schemas referenciados:

Quaisquer modificações feitas no schema original serão refletidas no schema que o referencia.

O schema referenciado não pode ser editado diretamente; para fazer alterações, você pode:

Clicar no nome do schema para navegar até o schema original e editá-lo.

Ao clicar em Desreferenciar no schema, o schema será transformado em uma série de propriedades independentes, permitindo que você as edite individualmente.

Se precisar modificar a definição de uma propriedade específica de forma independente, você pode optar por Desreferenciar essa propriedade, permitindo modificações individuais. Quaisquer alterações no schema original não afetarão a propriedade desreferenciada.

Nos casos em que nem todas as propriedades do schema referenciado forem necessárias no endpoint, você pode clicar em Ocultar para ocultar propriedades desnecessárias.

Composição de Schema

Se uma propriedade na sua estrutura de dados puder ter vários tipos de dados possíveis, você poderá usar a Composição de Schema para combinar vários schemas.

O Apidog oferece suporte às seguintes palavras-chave de composição:

Palavra-chave	Descrição
allOf (AND)	Especifica que a propriedade deve obedecer a todos os schemas definidos na composição.
anyOf (OR)	Especifica que a propriedade pode estar em conformidade com qualquer um dos schemas listados na composição.
oneOf (XOR)	Especifica que a propriedade deve obedecer a um, e somente um, dos schemas definidos na composição.

Depois de selecionar Composição de Schema, subpropriedades chamadas "0" e "1" aparecerão sob a propriedade, representando cada schema dentro da composição. Você pode modificar o tipo de schema de cada subpropriedade e adicionar schemas adicionais conforme necessário.

Na documentação da API, a Composição de Schema será exibida assim:

Você observará os dois objetos opcionais em OneOf. Se quiser exibir os nomes deles como mostrado na imagem, você precisará inserir os nomes no campo title no Editor de Tipo.

Personalização

Ao escolher "Personalizar", você pode editar diretamente o JSON Schema dentro do editor.

Configurações da Propriedade

Para cada propriedade, há vários botões localizados ao lado do tipo de dados:

Botão	Descrição
*	Indica se a propriedade é obrigatória.
N	Especifica se a propriedade permite valores nulos.
Settings	Permite que você edite configurações avançadas no Editor de Tipo.

Editor de Tipo

O Editor de Tipo descreve visualmente uma propriedade em conformidade com JSON Schema.

Depois que essas configurações avançadas forem configuradas, elas entrarão em vigor nas seguintes áreas:

Ao adicionar exemplos de resposta, você pode clicar para gerar automaticamente com base nas configurações.

Elas serão exibidas na documentação da API.

No corpo da requisição, você pode clicar para gerar automaticamente com base nas configurações.

Ao enviar uma requisição, os dados retornados serão validados automaticamente em relação às configurações.

No serviço de mock, os dados de resposta serão gerados com base nas configurações.

Propriedade Enumerada

Para os tipos String, Integer e Number, o Apidog oferece suporte a enum. Ao ativar o seletor de enum, você pode adicionar valores e descrições de enum. Além disso, você pode realizar Edição em Massa para valores de enum.

Mock

Além das configurações avançadas na propriedade, você pode especificar conteúdo de mock para campos preenchendo valores de mock. Valores de mock têm precedência sobre as configurações nas configurações avançadas.

Valores de mock oferecem suporte à sintaxe Faker.js, permitindo que você escolha os dados faker desejados diretamente nas opções do menu suspenso.

Valores de mock também podem ser inseridos como valores fixos.

Configurações de XML

Para dados XML, o Editor de Tipo no Apidog oferece Configurações de XML adicionais. Você pode ativar o seletor XML, configurar propriedades como nome da tag, namespace etc. e visualizar a estrutura XML correspondente.

HashMap, Dicionário, Array

HashMap, também conhecido como Map, dicionário ou array associativo. É uma coleção de pares chave-valor, em que os nomes das chaves podem ser qualquer conteúdo, em vez de predefinidos.

A especificação OpenAPI oferece suporte à definição de um HashMap com chaves string. Isso é feito definindo o tipo do elemento como object e, em seguida, usando a palavra-chave additionalProperties para especificar o tipo dos valores nos pares chave-valor.

Suponha que exista uma API de consulta de informações de usuário, e o formato dos dados retornados tenha os seguintes requisitos:

Os dados retornados são um objeto

Os elementos filhos do objeto são pares chave-valor de um HashMap

O ID do usuário é a chave, e as informações do usuário são o valor

Para definir isso no Apidog:

Crie um novo schema e nomeie-o como "UserProfiles".

Em "UserProfiles", especifique o nó raiz como um tipo "object". Em seguida, clique em Configuração Avançada, defina additionalProperties como Permitir e clique no botão Settings à direita.

No pop-up, adicione as informações de usuário necessárias, com o nome e o email do usuário como campos do objeto. Ele salva automaticamente.

Adição de campos de informações de usuário

Nas respostas da documentação da API, referencie o schema no nó raiz e selecione "user profiles" que você acabou de criar.

Referência ao schema de perfis de usuário

Clique em salvar e, em seguida, você poderá ver o schema definido e os valores de exemplo no exemplo de resposta de retorno dentro da documentação da API.

Exemplo de schema na documentação da API

Objetos com additionalProperties

À medida que o trabalho de desenvolvimento real evolui, os objetos retornados pela API podem ter additionalProperties em comparação com o objeto originalmente definido. De acordo com a especificação OpenAPI, essa situação também pode ser tratada usando o recurso "additionalProperties".

Suponha que agora exista uma API de consulta de informações de usuário, em que os campos de resposta originalmente definidos ao consultar informações de usuário por ID de usuário eram name e email. Agora, com a atualização do sistema, você deseja incluir outros campos.

Ao editar a documentação da API, você pode defini-la da seguinte forma: no nó raiz do modelo de dados, clique em Configurações Avançadas, defina additionalProperties como Permitir e defina o tipo de valor do campo como any.

Então você poderá ver a estrutura de dados definida e os valores de exemplo na documentação da API.

Estrutura de dados com additionalProperties

Tuplas

Normalmente, os elementos internos de um array devem ser do mesmo tipo, enquanto tuplas podem conter diferentes tipos de dados. Se você quiser definir uma tupla que inclua tipos string e integer, como dados do tipo (0,"A",2,"C"), poderá definir o tipo do elemento como array no modelo de dados, depois definir o tipo de items como anyOf no padrão de combinação e, em seguida, adicionar elementos filhos dos tipos string e integer, respectivamente.

TIP

Se você quiser gerar vários elementos ao gerar exemplos, especifique o número mínimo e máximo de elementos nas configurações avançadas do nó raiz.

Depois de salvar, clique em Gerar Automaticamente na documentação da API para ver a estrutura de dados definida e os valores de exemplo.

Você também pode ver os valores de exemplo da tupla na resposta de retorno na documentação.

Ferramentas

O Editor de Schema no Apidog fornece várias ferramentas altamente úteis.

Ferramenta	Descrição
Generate from JSON etc.	Esta ferramenta permite que você gere schemas automaticamente a partir de JSON, dados XML e outras fontes, ou diretamente de estruturas de tabelas de banco de dados. Saiba mais sobre Gerar schemas a partir de JSON etc..
Preview	Esta ferramenta cria dados de mock que seguem a definição do schema, fornecendo uma prévia dos dados esperados.
Generate code	Esta ferramenta pode produzir código de definição de estrutura de dados em várias linguagens de programação. Saiba mais sobre Gerar código.
JSON Schema	Esta ferramenta permite a edição direta de schemas JSON para ajustes finos e personalização.

FAQ

P: Se uma propriedade string tiver vários valores enumerados e for usada em vários locais, como esse enum pode ser referenciado de forma consistente em todos eles?

R: Você pode definir essa propriedade como um schema independente composto por uma única propriedade, permitindo que ela seja referenciada de forma consistente em diferentes partes da documentação da API.

Utilizando o Editor de Schema#

Criando um Schema#

Tipo de Propriedade#

Referenciando Outros Schemas#

Composição de Schema#

Personalização#

Configurações da Propriedade#

Editor de Tipo#

Propriedade Enumerada#

Mock#

Configurações de XML#

HashMap, Dicionário, Array#

Objetos com additionalProperties#

Tuplas#

Ferramentas#

FAQ#

Utilizando o Editor de Schema

Criando um Schema

Tipo de Propriedade

Referenciando Outros Schemas

Composição de Schema

Personalização

Configurações da Propriedade

Editor de Tipo

Propriedade Enumerada

Mock

Configurações de XML

HashMap, Dicionário, Array

Objetos com additionalProperties

Tuplas

Ferramentas

FAQ