Pular para o conteúdo

Geração de Schemas

Toda struct que você passa para Body, Responses ou Params é convertida em um schema OpenAPI por reflexão. Structs nomeadas são registradas uma vez sob #/components/schemas/ e referenciadas por $ref onde quer que apareçam, então um Todo usado em três respostas é descrito uma única vez e compartilhado.

type Todo struct {
ID int `json:"id" doc:"Unique identifier" example:"1"`
Title string `json:"title" doc:"Title of the task" example:"Buy milk"`
Done bool `json:"done" doc:"Whether completed" example:"false"`
Priority string `json:"priority" validate:"oneof=low medium high"`
CreatedAt time.Time `json:"created_at"`
}

As mesmas tags que você escreve para binding e validação orientam o schema você não anota os tipos duas vezes:

Tag Efeito
json Nome da propriedade no schema. json:"-" omite o campo.
validate Enriquece o schema com restrições e format (veja abaixo).
doc Define a description da propriedade.
example Define o example da propriedade, convertido para número ou bool quando o tipo do campo é numérico ou booleano.

A reflexão lê cada regra validate e traduz as que têm equivalente no JSON schema. Regras de comprimento e faixa se aplicam de forma diferente a strings e números:

tag validate Saída no schema
required Campo adicionado ao array required do schema
min=3 (string) minLength: 3
max=100 (string) maxLength: 100
min=1 (numérico) minimum: 1
max=100 (numérico) maximum: 100
gt=0 (numérico) exclusiveMinimum: 0
lt=100 (numérico) exclusiveMaximum: 100
len=10 (string) minLength: 10, maxLength: 10
email format: email
uuid, uuid3, uuid4, uuid5 format: uuid
url, uri, http_url format: uri
datetime format: date-time
oneof=a b c enum: ["a", "b", "c"]

Regras que o gerador não reconhece são ignoradas, então suas tags de validação podem carregar qualquer regra que o Kori valide apenas as relevantes para o schema aparecem na especificação.

Um campo é required quando sua tag validate contém required e não é um ponteiro. Campos ponteiro são o oposto: são tratados como nullable seu tipo vira ["type", "null"] no OpenAPI 3.1 e são sempre excluídos de required. Isso espelha como o Kori vincula campos opcionais, onde um *string distingue “ausente” de “vazio”:

type UpdateTodoBody struct {
Title *string `json:"title" validate:"omitempty,min=1,max=200"` // nullable, opcional
Done *bool `json:"done"` // nullable, opcional
Priority string `json:"priority" validate:"required,oneof=low medium high"` // obrigatório
}

Tipos Go mapeiam para schemas como você esperaria: inteiros viram integer (com formatos int32/int64), floats viram number, bool vira boolean, slices viram array com um schema items, e maps viram um object com additionalProperties. Structs aninhadas são registradas e referenciadas como qualquer outro schema nomeado.

Alguns tipos padrão têm um formato de transmissão que não corresponde à sua representação Go, então o gerador emite um schema fixo para eles em vez de refletir seus campos:

Tipo Go Schema
time.Time string, format: date-time
net/url.URL string, format: uri
net.IP string, format: ipv4
encoding/json.RawMessage sem tipo (qualquer JSON)
github.com/google/uuid.UUID string, format: uuid

Structs embutidas (anônimas) são inlinadas seus campos e entradas required são mescladas no schema externo em vez de referenciadas separadamente:

type Meta struct {
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
type Todo struct {
Meta // created_at + updated_at aparecem diretamente em Todo
ID int `json:"id"`
Title string `json:"title"`
}

Instanciações de genéricos recebem um nome de componente válido substituindo os colchetes do parâmetro de tipo: SuccessResponse[HomeResponse] é registrado como SuccessResponse_HomeResponse. Isso permite documentar tipos de envelope genéricos um wrapper compartilhado SuccessResponse[T], por exemplo sem nenhuma nomeação manual.

Tipos recursivos e auto-referenciais são tratados com segurança: um tipo que se refere a si mesmo resolve para um $ref em vez de recorrer infinitamente.