Criar um Schema

Utilizar o Editor de Schemas

O Editor de Schemas é uma ferramenta poderosa que ajuda a conceber e modelar as estruturas de dados que a sua API utiliza. Baseia-se em JSON Schema e é utilizado para conceber estruturas de dados JSON ou XML.

Utilize o Editor de Schemas para:

Desenvolver corpos de pedidos e respostas da API adaptados a endpoints de API específicos.

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

Todos os schemas começam com um objeto raiz. Para criar um schema, adicione propriedades a este objeto raiz.

Adicionar Propriedades

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

Nomear a Sua Propriedade

Introduza o nome (ou chave) da propriedade.

Selecionar o Tipo de Propriedade

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

Definições Avançadas

Utilize o Editor de Tipos para atribuir tipos de dados, como valores predefinidos e formatos, a cada propriedade.

Gerir Propriedades

Reordene propriedades movendo-as, copiando-as ou eliminando-as. Também pode enriquecer as propriedades com descrições e marcá-las como obrigatórias.

Métodos Alternativos

Também pode criar novos schemas importando a partir de tabelas de bases de dados ou ficheiros de JSON schema. Saiba mais sobre Gerar Schemas a partir de JSON etc..

Tipo de Propriedade

Em conformidade com a norma JSON Schema, o Editor de Schemas do Apidog suporta os seguintes tipos de dados básicos:

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, de precisão arbitrária, correspondente ao valor JSON "number".
string	Representa uma cadeia de caracteres Unicode, correspondente ao valor JSON "string".

Tipo de Dados Array

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

Além das estruturas de dados padrão mencionadas anteriormente, o Editor de Schemas do Apidog também suporta o seguinte:

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

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

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

Personalização: Permite aos utilizadores personalizar e adaptar o schema para cumprir requisitos específicos e necessidades de modelação de dados.

Referenciar Outros Schemas

Pode utilizar a funcionalidade "Referenciar outros schemas" para referenciar schemas definidos anteriormente.

Depois de referenciar outro schema, pode ver o schema referenciado no Editor de Schemas.

Pontos principais sobre schemas referenciados:

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

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

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

Ao clicar em Remover referência no schema, o schema será transformado numa série de propriedades independentes, permitindo-lhe editá-las individualmente.

Se precisar de modificar independentemente a definição de uma propriedade específica, pode optar por Remover referência dessa propriedade, permitindo modificações individuais. Quaisquer alterações ao schema original não afetarão a propriedade cuja referência foi removida.

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

Composição de Schemas

Se uma propriedade na sua estrutura de dados puder ter vários tipos de dados possíveis, pode utilizar a Composição de Schemas para combinar vários schemas.

O Apidog suporta as seguintes palavras-chave de composição:

Palavra-chave	Descrição
allOf (AND)	Especifica que a propriedade deve cumprir 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 cumprir um e apenas um dos schemas definidos na composição.

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

Na documentação da API, a Composição de Schemas será apresentada assim:

Irá reparar nos dois objetos opcionais sob OneOf. Se pretender apresentar os respetivos nomes conforme mostrado na imagem, deve introduzir os nomes no campo title no Editor de Tipos.

Personalização

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

Definições de Propriedades

Para cada propriedade, existem vários botões localizados junto ao tipo de dados:

Botão	Descrição
*	Indica se a propriedade é obrigatória.
N	Especifica se a propriedade permite valores nulos.
Definições	Permite-lhe editar definições avançadas no Editor de Tipos.

Editor de Tipos

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

Depois de configuradas estas definições avançadas, estas terão efeito nas seguintes áreas:

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

Serão apresentadas na documentação da API.

No corpo do pedido, pode clicar para gerar automaticamente com base nas definições.

Ao enviar um pedido, os dados devolvidos serão validados automaticamente em relação às definições.

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

Propriedade Enumerada

Para os tipos String, Integer e Number, o Apidog suporta enum. Ao ativar o comutador de enum, pode adicionar valores e descrições de enum. Além disso, pode efetuar Edição em Massa para valores de enum.

Mock

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

Os valores de mock suportam a sintaxe Faker.js, permitindo-lhe escolher os dados faker pretendidos diretamente a partir das opções da lista pendente.

Os valores de mock também podem ser introduzidos como valores fixos.

Definições de XML

Para dados XML, o Editor de Tipos no Apidog oferece Definições de XML adicionais. Pode ativar o comutador XML, configurar propriedades como nome da etiqueta, namespace, etc., e pré-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 suporta a definição de um HashMap com chaves de cadeia de caracteres. Isto é feito definindo o tipo de elemento como object e, em seguida, utilizando a palavra-chave additionalProperties para especificar o tipo dos valores nos pares chave-valor.

Suponha que existe uma API de consulta de informações de utilizadores e que o formato dos dados devolvidos tem os seguintes requisitos:

Os dados devolvidos são um objeto

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

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

Para definir isto no Apidog:

Crie um novo schema e dê-lhe o nome "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 Definições à direita.

Na janela pop-up, adicione as informações de utilizador necessárias, com o nome e o email do utilizador como campos do objeto. Guarda automaticamente.

Adicionar campos de informações de utilizador

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

Referenciar schema de perfis de utilizador

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

Exemplo de schema na documentação da API

Objetos com additionalProperties

À medida que o trabalho de desenvolvimento real itera, os objetos devolvidos pela API podem ter additionalProperties em comparação com o objeto originalmente definido. De acordo com a especificação OpenAPI, esta situação também pode ser tratada utilizando a funcionalidade "additionalProperties".

Suponha que existe agora uma API de consulta de informações de utilizadores, em que os campos de resposta originalmente definidos ao consultar informações de utilizador por ID de utilizador eram name e email. Agora, com a atualização do sistema, pretende incluir outros campos.

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

Em seguida, pode ver a estrutura de dados definida e os valores de exemplo na documentação da API.

Estrutura de dados com additionalProperties

Tuplos

Normalmente, os elementos internos de um array devem ser do mesmo tipo, enquanto os tuplos podem conter diferentes tipos de dados. Se pretender definir um tuplo que inclua tipos string e integer, como dados do tipo (0,"A",2,"C"), pode definir o tipo de 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 do tipo string e integer, respetivamente.

TIP

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

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

Também pode ver os valores de exemplo do tuplo na resposta devolvida na documentação.

Ferramentas

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

Ferramenta	Descrição
Gerar a partir de JSON etc.	Esta ferramenta permite-lhe gerar automaticamente schemas a partir de JSON, dados XML e outras fontes, ou diretamente a partir de estruturas de tabelas de bases de dados. Saiba mais sobre Gerar schemas a partir de JSON etc..
Pré-visualização	Esta ferramenta cria dados de mock que cumprem a definição do schema, fornecendo uma pré-visualização dos dados esperados.
Gerar código	Esta ferramenta pode produzir código de definição de estruturas 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 JSON schemas para ajuste fino e personalização.

FAQ

P: Se uma propriedade de cadeia de caracteres tiver vários valores enumerados e for utilizada em vários locais, como pode este enum ser referenciado de forma consistente em todo o lado?

R: Pode definir esta propriedade como um schema autónomo composto por uma única propriedade, permitindo que seja referenciada de forma consistente em diferentes partes da documentação da API.

Criar um Schema

Utilizar o Editor de Schemas#

Criar um Schema#

Tipo de Propriedade#

Referenciar Outros Schemas#

Composição de Schemas#

Personalização#

Definições de Propriedades#

Editor de Tipos#

Propriedade Enumerada#

Mock#

Definições de XML#

HashMap, Dicionário, Array#

Objetos com additionalProperties#

Tuplos#

Ferramentas#

FAQ#

Utilizar o Editor de Schemas

Criar um Schema

Tipo de Propriedade

Referenciar Outros Schemas

Composição de Schemas

Personalização

Definições de Propriedades

Editor de Tipos

Propriedade Enumerada

Mock

Definições de XML

HashMap, Dicionário, Array

Objetos com additionalProperties

Tuplos

Ferramentas

FAQ