Pacote openapi
Todas as funções e tipos exportados de github.com/douglasmai4/kori/openapi.
import "github.com/douglasmai4/kori/openapi"Gera um documento OpenAPI 3.1 a partir das rotas registradas com o Kori. O pacote é opcional e fica em um módulo próprio.
NewSpec
Seção intitulada “NewSpec”func NewSpec(cfg Config) *SpecCria o construtor da spec.
spec := openapi.NewSpec(openapi.Config{ Title: "Todos API", Version: "1.0.0",})type Config struct { Title string Version string Description string Servers []Server}
type Server struct { URL string `json:"url"` Description string `json:"description,omitempty"`}Spec.Route
Seção intitulada “Spec.Route”func (s *Spec) Route(cfg RouteConfig) kori.OptionRetorna uma kori.Option que adiciona a rota ao documento. Passe como último argumento de qualquer função de método.
kori.GET(r, "/todos", listTodos, spec.Route(openapi.RouteConfig{ Summary: "List all todos", Params: &ListParams{}, Responses: map[int]any{200: &TodoList{}},}))RouteConfig
Seção intitulada “RouteConfig”type RouteConfig struct { OperationID string Summary string Description string Tags []string Deprecated bool Params any Body any Responses map[int]any Security []SecurityRequirement NoSecurity bool}| Campo | Função |
|---|---|
OperationID |
Operation id explícito. Gerado a partir do método e do path quando vazio. |
Params |
Ponteiro para struct com tags path, query e header. Cada campo vira um parâmetro. |
Body |
Ponteiro para o tipo do body JSON. |
Responses |
Status → tipo da resposta. nil documenta uma resposta sem body. |
Security |
Sobrescreve a segurança global nesta rota. |
NoSecurity |
Marca a rota como pública mesmo com segurança global definida. |
Servindo o documento
Seção intitulada “Servindo o documento”func (s *Spec) JSONHandler() http.HandlerFuncfunc (s *Spec) YAMLHandler() http.HandlerFuncfunc (s *Spec) ScalarHandler(specURL string, opts ...ScalarOptions) http.HandlerFuncr.Get("/openapi.json", spec.JSONHandler())r.Get("/openapi.yaml", spec.YAMLHandler())r.Get("/docs", spec.ScalarHandler("/openapi.json"))ScalarHandler serve uma página HTML que carrega o Scalar via jsDelivr apontando para specURL.
ScalarOptions
Seção intitulada “ScalarOptions”type ScalarOptions struct { Theme string // padrão: "default" DarkMode bool HideModels bool HideDownloadButton bool DefaultOpenAllTags bool CustomCSS string}Tags de schema
Seção intitulada “Tags de schema”Structs são convertidas por reflection e registradas uma vez em #/components/schemas.
| Tag | Efeito |
|---|---|
json |
Nome da propriedade; json:"-" omite o campo |
path, query, header |
Nome e local do parâmetro dentro de Params |
validate |
Adiciona required, tamanho, intervalo, format e enum |
doc |
Define description |
example |
Define example, tipado conforme o campo |
Veja Geração de schemas para o mapeamento completo de validate.
Segurança
Seção intitulada “Segurança”Schemes
Seção intitulada “Schemes”func BearerAuth(bearerFormat ...string) SecuritySchemefunc BasicAuth() SecuritySchemefunc APIKeyAuth(name string, in APIKeyLocation) SecuritySchemefunc OAuth2(flows OAuthFlows) SecuritySchemefunc OpenIDConnect(discoveryURL string) SecuritySchemetype APIKeyLocation string
const ( InHeader APIKeyLocation = "header" InQuery APIKeyLocation = "query" InCookie APIKeyLocation = "cookie")Registrando e exigindo
Seção intitulada “Registrando e exigindo”func (s *Spec) AddSecurityScheme(name string, scheme SecurityScheme)func (s *Spec) SetGlobalSecurity(reqs ...SecurityRequirement)
func Require(schemes ...string) SecurityRequirementfunc RequireScopes(scheme string, scopes ...string) SecurityRequirementspec.AddSecurityScheme("bearer", openapi.BearerAuth("JWT"))spec.AddSecurityScheme("apiKey", openapi.APIKeyAuth("X-API-Key", openapi.InHeader))spec.SetGlobalSecurity(openapi.Require("bearer"))Vários requisitos no slice significam qualquer um deles; vários esquemas dentro de um Require significam todos eles.
Tipos OAuth
Seção intitulada “Tipos OAuth”type OAuthFlows struct { Implicit *OAuthFlow Password *OAuthFlow ClientCredentials *OAuthFlow AuthorizationCode *OAuthFlow}
type OAuthFlow struct { AuthorizationURL string TokenURL string RefreshURL string Scopes map[string]string}Tipos do documento
Seção intitulada “Tipos do documento”Espelham os objetos do OpenAPI 3.1 e são exportados para inspeção e ferramentas. Raramente você os monta à mão.
| Tipo | Objeto OpenAPI |
|---|---|
Operation |
Operation |
Parameter |
Parameter (in: path, query, header) |
RequestBody |
Request Body |
Response, Responses |
Response, Responses |
MediaType |
Media Type |
Schema |
Schema (3.1, type pode ser lista para nullable) |
SecurityScheme |
Security Scheme |
SecurityRequirement |
Security Requirement |