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"`}Tags de struct
Seção intitulada “Tags de struct”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. |
Validação → schema
Seção intitulada “Validação → schema”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.
Obrigatório e nullable
Seção intitulada “Obrigatório e nullable”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 e genéricos
Seção intitulada “Structs embutidas e genéricos”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.