Modelos, enums e propriedades

Os modelos descrevem os dados da sua API. Um modelo carrega propriedades tipadas, e essas propriedades podem referenciar outros modelos ou enums.

Os enums

Um enum é um conjunto de valores fechado (por exemplo um estado draft / published / archived). Um design gere-os de duas maneiras:

• Enums nomeados — reutilizáveis, de primeiro nível. A partir da secção Enums, utilize Adicionar um enum, dê-lhe um nome e uma descrição, e depois Adicionar um valor para cada entrada. Uma propriedade (ou um parâmetro de rota) referencia-o depois pelo seu tipo.
• Enums inline — um conjunto anónimo declarado diretamente numa propriedade. Numa propriedade string / integer / number, um editor de chips Valores de enum permite-lhe enumerar os valores permitidos ali mesmo, sem criar um tipo nomeado.

Quando um enum inline merece ser partilhado, Extrair para um enum nomeado promove-o: cria o enum nomeado (reutilizando um enum existente com os mesmos valores, para evitar duplicados) e reescreve a propriedade para que o referencie. Os parâmetros de rota carregam também enums inline e a mesma ação Extrair — ver Rotas e CRUD.

As propriedades de um modelo

Na secção Modelos, selecione um modelo: as suas propriedades exibem-se numa tabela (Propriedade, Tipo, Sinalizadores, Exemplo). Utilize Adicionar uma propriedade para criar uma.

Uma propriedade pode ser do tipo:

• um primitivo: string, integer, number, boolean;
• um array (array<…>) ou um map (map<…>) de outro tipo;
• uma referência para outro modelo;
• uma referência para um enum.

Para um string, pode precisar um formato: email, uuid, date, date-time, uri, hostname, ipv4, password ou byte.

Para além do tipo, uma propriedade aceita numerosos campos: Descrição, Exemplo, Valor por omissão, Mínimo / Máximo, Comprimento mín / Comprimento máx, Padrão (regex), Mensagem de descontinuação, e — para as referências — um comportamento On delete.

Os sinalizadores

Uns sinalizadores qualificam a propriedade e exibem-se sob a forma de distintivos: obrigatório, nullable, único, imutável, searchable (pesquisável — ver Rotas e CRUD), descontinuado, só leitura, só escrita, e PII (dado pessoal).

Identidade e herança

Cada modelo tem os seus próprios ajustes:

• Identidade — a propriedade identificadora e a sua estratégia de geração (uuid, autoIncrement ou ulid). É este identificador que é ligado aos parâmetros {{id}} das rotas geradas.
• Herança — um modelo pode herdar de um pai; o filho exibe as propriedades do pai em só leitura, além das suas.
• Armazenamento e ciclo de vida — volumetria esperada, marcas temporais (created / updated) e eliminação suave (soft delete).

É também a partir destes ajustes que se lança Gerar o CRUD e Gerar as rotas de pesquisa — descritos na página seguinte.