Pular para o conteúdo

Documentando Rotas

spec.Route recebe um RouteConfig e retorna uma kori.Option. Tudo o que você quer na operação seu resumo, parâmetros, corpo da requisição e respostas é declarado nessa única struct, no ponto de chamada da rota que ela documenta:

kori.POST(r, "/todos", createTodo,
spec.Route(kopenapi.RouteConfig{
OperationID: "createTodo",
Summary: "Create a todo",
Description: "Adds a new todo item to the list.",
Tags: []string{"todos"},
Body: CreateTodoBody{},
Responses: map[int]any{
201: Todo{},
422: kori.HTTPError{},
},
}),
)
Campo Tipo Propósito
OperationID string Identificador único da operação. Gerado a partir do método + caminho se vazio.
Summary string Descrição curta, de uma linha, da operação.
Description string Explicação mais longa; aceita o CommonMark que a UI renderiza.
Tags []string Agrupa a operação sob uma ou mais tags na UI.
Deprecated bool Marca a operação como obsoleta.
Params any Uma struct cujas tags path/query/header viram parâmetros.
Body any Uma struct descrevendo o corpo da requisição. Ignorada em métodos sem corpo.
Responses map[int]any Código de status → tipo da resposta. nil significa sem corpo.
Security []SecurityRequirement Autenticação por rota, sobrescrevendo o padrão global. Ver Segurança.
NoSecurity bool Marca a operação como pública, limpando qualquer segurança global.

Params é uma struct normalmente a mesma que você vincula com kori.BindQuery ou kori.Bind anotada com path, query ou header. Cada campo anotado vira um parâmetro:

type ListTodosParams struct {
Priority string `query:"priority" validate:"omitempty,oneof=low medium high" doc:"Filter by priority"`
Page int `query:"page" validate:"min=0" doc:"Page number (0-based)" example:"0"`
Limit int `query:"limit" validate:"min=0,max=100" doc:"Items per page" example:"20"`
}
type TodoIDParams struct {
ID int `path:"id" validate:"required,min=1" doc:"Todo ID" example:"1"`
}

O nome da tag é o nome do parâmetro e sua localização (in). O tipo Go do campo vira o schema do parâmetro, e suas tags validate, doc e example o enriquecem exatamente como fazem nos schemas de corpo.

Duas regras sobre quando um parâmetro é required:

  • Parâmetros de caminho são sempre obrigatórios a especificação OpenAPI exige isso, então a tag path força o required independentemente das tags de validação.
  • Parâmetros de query e header são obrigatórios apenas quando sua tag validate contém required; caso contrário são opcionais. Um campo ponteiro nunca é obrigatório.

Structs embutidas (anônimas) são achatadas, então você pode compartilhar um conjunto comum de params embutindo-o:

type Pagination struct {
Page int `query:"page" validate:"min=0"`
Limit int `query:"limit" validate:"min=0,max=100"`
}
type ListTodosParams struct {
Pagination // contribui com page + limit
Priority string `query:"priority"`
}

Body é uma struct convertida em um schema de corpo JSON sob application/json e marcada como required:

type CreateTodoBody struct {
Title string `json:"title" validate:"required,min=1,max=200"`
Priority string `json:"priority" validate:"required,oneof=low medium high"`
}
kori.POST(r, "/todos", createTodo,
spec.Route(kopenapi.RouteConfig{
Body: CreateTodoBody{},
// ...
}),
)

O corpo só faz sentido para métodos que carregam um. Para GET, HEAD, DELETE, OPTIONS e TRACE, um Body é silenciosamente ignorado, então você pode reutilizar uma struct de config entre métodos sem que corpos de requisição perdidos apareçam em um GET.

Veja Geração de Schemas para saber como a struct e suas tags mapeiam para um JSON schema.

Responses mapeia um código de status HTTP para o tipo do corpo daquela resposta. O valor é transformado em um schema sob application/json; nil documenta uma resposta sem corpo:

Responses: map[int]any{
200: Todo{}, // 200 com um corpo Todo
201: []Todo{}, // 201 com um array de Todo
204: nil, // 204 No Content, sem corpo
404: kori.HTTPError{}, // formato de erro do kori
},

A description de cada resposta é preenchida a partir do texto padrão do seu código de status (200 → “OK”, 404 → “Not Found”). Documentar suas respostas de erro com kori.HTTPError{} mantém a especificação alinhada com o formato que o tratador de erros do Kori realmente retorna.

Se Responses estiver vazio, a operação recebe uma única resposta default sem schema válida, mas você quase sempre vai querer listar os códigos de status reais.

OperationID precisa ser único em toda a especificação; ferramentas o usam para nomear os métodos de cliente gerados. Deixe-o vazio e o módulo deriva um a partir do método e do caminho:

Padrão Método ID de operação
/todos GET list-todos
/todos/{id} GET get-todo
/todos POST create-todo
/todos/{id} PUT replace-todo
/todos/{id} PATCH update-todo
/todos/{id} DELETE delete-todo
/todos HEAD head-todos
/todos OPTIONS options-todos

O verbo vem do método (e de se o caminho termina em um parâmetro um GET numa coleção é list, um GET num item é get). Segmentos de versão como v1 ou v2 são descartados, e quando o verbo se refere a um único item o último substantivo do caminho é colocado no singular (todos → todo).

A geração cobre os formatos REST comuns; defina OperationID explicitamente sempre que quiser um nome específico ou a heurística não se encaixar na sua rota.