Pular para o conteúdo

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.

func NewSpec(cfg Config) *Spec

Cria 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"`
}
func (s *Spec) Route(cfg RouteConfig) kori.Option

Retorna 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{}},
}))
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.
func (s *Spec) JSONHandler() http.HandlerFunc
func (s *Spec) YAMLHandler() http.HandlerFunc
func (s *Spec) ScalarHandler(specURL string, opts ...ScalarOptions) http.HandlerFunc
r.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.

type ScalarOptions struct {
Theme string // padrão: "default"
DarkMode bool
HideModels bool
HideDownloadButton bool
DefaultOpenAllTags bool
CustomCSS string
}

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.

func BearerAuth(bearerFormat ...string) SecurityScheme
func BasicAuth() SecurityScheme
func APIKeyAuth(name string, in APIKeyLocation) SecurityScheme
func OAuth2(flows OAuthFlows) SecurityScheme
func OpenIDConnect(discoveryURL string) SecurityScheme
type APIKeyLocation string
const (
InHeader APIKeyLocation = "header"
InQuery APIKeyLocation = "query"
InCookie APIKeyLocation = "cookie"
)
func (s *Spec) AddSecurityScheme(name string, scheme SecurityScheme)
func (s *Spec) SetGlobalSecurity(reqs ...SecurityRequirement)
func Require(schemes ...string) SecurityRequirement
func RequireScopes(scheme string, scopes ...string) SecurityRequirement
spec.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.

type OAuthFlows struct {
Implicit *OAuthFlow
Password *OAuthFlow
ClientCredentials *OAuthFlow
AuthorizationCode *OAuthFlow
}
type OAuthFlow struct {
AuthorizationURL string
TokenURL string
RefreshURL string
Scopes map[string]string
}

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