Magic Types

I "Magic Types" sono una forma breve per gli schemi Swagger: invece di un verboso oggetto schema, scrivi una stringa che cattura il tipo, un formato opzionale, un esempio e se il campo è obbligatorio.

Entrambi gli stack, portata diversa

Su Express, i Magic Types descrivono gli schemi swaggerModel e i tipi _<verb>Swagger, alimentando OpenAPI e la generazione dei tipi. Su Bun/Elysia, lo stesso DSL è accettato all'interno del _<verb>Swagger di una classe (requestBody, responses, parameters) e del registro models, ed espanso nel documento OpenAPI nativo. In entrambi i casi i Magic Types guidano solo la documentazione, non la validazione delle richieste (Express usa express-validator, Elysia usa TypeBox). La generazione dei tipi è solo per Express.

Provalo

Scrivi un Magic Type qui sotto; lo schema OpenAPI e il tipo TypeScript si aggiornano mentre digiti:

Magic Type

type[::format][|example][!|?] · arrays [] · refs @Model

OpenAPI schema

{
  "type": "string",
  "format": "email",
  "example": "john@example.com!"
}

required follows defaultRequiredValueForModels

TypeScript

type T = string;

Sintassi

type[::format][|example][!|?]

• type: un tipo di dato base o un riferimento a un altro modello. I tipi base sono string, number, integer, boolean, array, object, Date e ObjectId. I formati delle stringhe sono date, date-time, password, byte, binary.
• ::format: (opzionale) il formato per la validazione (email, date-time, ecc.).
• |example: (opzionale) un valore di esempio per la documentazione.
• !: (opzionale) segna il campo come obbligatorio (ha la precedenza sul default).
• ?: (opzionale) segna il campo come opzionale (ha la precedenza sul default).

Esempi

Magic Type	Descrizione	Equivalente Swagger
string	Una semplice stringa	{ type: "string" }
string::email	Una stringa con formato email	{ type: "string", format: "email" }
number!	Un numero obbligatorio	{ type: "number" }, required: true
boolean?	Un booleano opzionale	{ type: "boolean" }, required: false
string|John Doe	Una stringa con un esempio	{ type: "string", example: "John Doe" }
string::email|john@example.com	Email con esempio	{ type: "string", format: "email", example: "john@example.com" }

Array

Aggiungi [] per un array.

Magic Type	Descrizione	Equivalente Swagger
string[]	Array di stringhe	{ type: "array", items: { type: "string" } }
number[]!	Array di numeri obbligatorio	{ type: "array", items: { type: "number" } }, required: true
@User[]	Array di modelli User	{ type: "array", items: { $ref: "#/components/schemas/User" } }

Riferimenti a modelli

Referenzia un altro schema con @ seguito dal suo nome.

Magic Type	Descrizione	Equivalente Swagger
@User	Riferimento al modello User	{ $ref: "#/components/schemas/User" }
@User!	Riferimento User obbligatorio	{ $ref: "#/components/schemas/User" }, required: true
@User?	Riferimento User opzionale	{ $ref: "#/components/schemas/User" }, required: false

Tipi personalizzati

Definisci tipi riutilizzabili in config.customTypes, poi usali come qualsiasi tipo base.

Configurazione

// efesto config
customTypes: {
  ObjectId: "string",
  Date: { type: "string", format: "date-time" },
  Price: { type: "number", format: "float" }
}

Utilizzo

properties: {
  id: "ObjectId",
  createdAt: "Date",
  cost: "Price"
}

Un modello completo

swaggerModel = {
  modelName: "User",
  schemas: [
    {
      name: "User",
      properties: {
        id: "ObjectId", // Tipo personalizzato
        username: "string!", // Stringa obbligatoria
        email: "string::email!", // Email obbligatoria
        age: "number?", // Numero opzionale
        tags: "string[]", // Array di stringhe
        profile: "@UserProfile", // Riferimento a un altro modello
        createdAt: "Date", // Tipo personalizzato
      },
    },
  ],
};

Campi nullable

Se hai configurato defaultNullableOnOptionalFields: true, usare l'operatore ? segnerà il campo anche come nullable: true nello schema Swagger generato.

// Con defaultNullableOnOptionalFields: true
"string?";
// Diventa: { type: "string", nullable: true } (e rimosso dalla lista required)