openapi package
Every exported function and type in github.com/douglasmai4/kori/openapi.
import "github.com/douglasmai4/kori/openapi"Builds an OpenAPI 3.1 document from routes registered with Kori. The package is optional and lives in its own module.
NewSpec
Section titled “NewSpec”func NewSpec(cfg Config) *SpecCreates the spec builder.
spec := openapi.NewSpec(openapi.Config{ Title: "Todos API", Version: "1.0.0",})Config
Section titled “Config”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
Section titled “Spec.Route”func (s *Spec) Route(cfg RouteConfig) kori.OptionReturns a kori.Option that adds the route to the document. Pass it as the last argument to any method function.
kori.GET(r, "/todos", listTodos, spec.Route(openapi.RouteConfig{ Summary: "List all todos", Params: &ListParams{}, Responses: map[int]any{200: &TodoList{}},}))RouteConfig
Section titled “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}| Field | Purpose |
|---|---|
OperationID |
Explicit operation id. Generated from method and path when empty. |
Params |
Pointer to a struct with path, query and header tags. Each field becomes a parameter. |
Body |
Pointer to the JSON request body type. |
Responses |
Status code → response type. nil documents a response with no body. |
Security |
Overrides the global security for this route. |
NoSecurity |
Marks the route as public even when global security is set. |
Serving the document
Section titled “Serving the document”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 serves an HTML page that loads Scalar from jsDelivr and points it at specURL.
ScalarOptions
Section titled “ScalarOptions”type ScalarOptions struct { Theme string // defaults to "default" DarkMode bool HideModels bool HideDownloadButton bool DefaultOpenAllTags bool CustomCSS string}Schema tags
Section titled “Schema tags”Struct types are converted by reflection and registered once under #/components/schemas.
| Tag | Effect |
|---|---|
json |
Property name; json:"-" omits the field |
path, query, header |
Parameter name and location inside Params |
validate |
Adds required, length, range, format and enum constraints |
doc |
Sets description |
example |
Sets example, typed to the field |
See Schema generation for the full validate mapping.
Security
Section titled “Security”Schemes
Section titled “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")Registering and requiring
Section titled “Registering and requiring”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"))Several requirements in one slice mean any of them; several schemes inside one Require mean all of them.
OAuth types
Section titled “OAuth types”type OAuthFlows struct { Implicit *OAuthFlow Password *OAuthFlow ClientCredentials *OAuthFlow AuthorizationCode *OAuthFlow}
type OAuthFlow struct { AuthorizationURL string TokenURL string RefreshURL string Scopes map[string]string}Document types
Section titled “Document types”These mirror the OpenAPI 3.1 objects and are exported for inspection and tooling. You rarely build them by hand.
| Type | OpenAPI object |
|---|---|
Operation |
Operation |
Parameter |
Parameter (in: path, query, header) |
RequestBody |
Request Body |
Response, Responses |
Response, Responses |
MediaType |
Media Type |
Schema |
Schema (3.1, type may be a list for nullable) |
SecurityScheme |
Security Scheme |
SecurityRequirement |
Security Requirement |