openapi

type APIKey ¶

type APIKey struct {
	Name string
	In   APIKeyIn
}

APIKey is the apiKey scheme.

type APIKeyIn ¶

type APIKeyIn string

APIKeyIn identifies where an API key is presented.

const (
	APIKeyInHeader APIKeyIn = "header"
	APIKeyInQuery  APIKeyIn = "query"
	APIKeyInCookie APIKeyIn = "cookie"
)

type Collector ¶

type Collector struct {
	// contains filtered or unexported fields
}

Collector orchestrates OpenAPI spec generation across the kit. It owns a Reflector, holds per-route annotation registrations, and serves the final spec JSON.

Lifetime: one Collector per server. Constructed by rest.WithOpenAPI; fed by router.build as routes are registered; queried by the spec endpoint at request time.

All public methods are safe for concurrent use.

func NewCollector(ref Reflector, cfg SpecConfig) (*Collector, error)

func (c *Collector) AnnotateOperation(method, pattern string, fn func(oc OperationContext) error)

func (c *Collector) CollectOperation(
	method, pattern string,
	handler http.Handler,
	annotations ...func(oc OperationContext) error,
) error

func (c *Collector) ServeHTTP(w http.ResponseWriter, _ *http.Request)

func (c *Collector) SkipPath(path string)

func (c *Collector) SpecConfig() SpecConfig

type ErrorBody ¶

type ErrorBody struct {
	Error  string `json:"error"`
	Status int    `json:"status"`
}

ErrorBody is the canonical error response shape emitted by the kit's default plain-JSON error encoder. Op-level Errors() declares responses with this body.

type ExternalDocsInfo ¶

type ExternalDocsInfo struct {
	URL         string
	Description string
}

ExternalDocsInfo is the external documentation block attached to the spec root.

type HTTPBasic ¶

type HTTPBasic struct{}

HTTPBasic represents HTTP basic authentication.

type HTTPBearer ¶

type HTTPBearer struct {
	BearerFormat string
}

HTTPBearer represents an HTTP bearer-token scheme (most common for JWT-based auth). BearerFormat is informational, e.g. "JWT".

type MutualTLS ¶

type MutualTLS struct{}

MutualTLS represents the mutualTLS scheme.

type OAuth2 ¶

type OAuth2 struct {
	ClientCredentials *OAuth2ClientCredentialsFlow
	AuthorizationCode *OAuth2AuthorizationCodeFlow
	Implicit          *OAuth2ImplicitFlow
	Password          *OAuth2PasswordFlow
}

OAuth2 represents the oauth2 scheme.

Exactly one of Flow* fields should be populated per scheme. Callers should usually use the OAuth2* builder helpers rather than constructing this struct directly.

type OAuth2AuthorizationCodeFlow ¶

type OAuth2AuthorizationCodeFlow struct {
	AuthorizationURL string
	TokenURL         string
	Scopes           map[string]string
}

OAuth2AuthorizationCodeFlow describes the authorization-code flow.

type OAuth2ClientCredentialsFlow ¶

type OAuth2ClientCredentialsFlow struct {
	TokenURL string
	Scopes   map[string]string
}

OAuth2ClientCredentialsFlow describes the client-credentials flow.

type OAuth2ImplicitFlow ¶

type OAuth2ImplicitFlow struct {
	AuthorizationURL string
	Scopes           map[string]string
}

OAuth2ImplicitFlow describes the (deprecated) implicit flow.

type OAuth2PasswordFlow ¶

type OAuth2PasswordFlow struct {
	TokenURL string
	Scopes   map[string]string
}

OAuth2PasswordFlow describes the (deprecated) password flow.

type OIDC ¶

type OIDC struct {
	DiscoveryURL string
}

OIDC represents the openIdConnect scheme. The discovery URL points at the issuer's well-known configuration endpoint.

type OpOpt ¶

type OpOpt func(OperationContext) error

OpOpt is a per-operation option. The kit composes a slice of these into a single function that runs against the OperationContext during spec collection.

func Deprecated() OpOpt

func Description(s string) OpOpt

func Errors(statuses ...int) OpOpt

func ExternalDocs(url, description string) OpOpt

func NoSecurity() OpOpt

func OperationID(id string) OpOpt

func Raw(fn func(oc OperationContext) error) OpOpt

func RequestExample(name string, example any) OpOpt

func Response(status int, body any) OpOpt

func ResponseExample(status int, name string, example any) OpOpt

func Security(schemeNames ...string) OpOpt

func Summary(s string) OpOpt

func Tags(tags ...string) OpOpt

type OperationContext ¶

type OperationContext interface {
	// AddRequest declares the request body shape. Pass a zero value
	// of the request struct; the underlying reflector walks its
	// json/jsonapi tags to produce the JSON Schema.
	AddRequest(body any)

	// AddResponse declares a response for the given HTTP status.
	// May be called multiple times to declare error responses.
	AddResponse(status int, body any)

	// SetSummary sets the operation's short, single-line summary.
	SetSummary(s string)

	// SetDescription sets the operation's longer prose description.
	SetDescription(s string)

	// SetTags groups the operation under one or more tags. The UI
	// uses these to organise the operation list.
	SetTags(tags ...string)

	// SetOperationID sets a globally-unique operation ID. If unset,
	// the reflector derives one from method+path.
	SetOperationID(id string)

	// SetDeprecated marks the operation as deprecated.
	SetDeprecated(b bool)

	// AddRequestExample attaches a named example to the request body.
	AddRequestExample(name string, example any)

	// AddResponseExample attaches a named example to a specific
	// response status.
	AddResponseExample(status int, name string, example any)

	// SetSecurity requires the operation be authorised by all the
	// named schemes (AND semantics). Schemes must be declared at
	// spec level via SecurityScheme. Pass no arguments to explicitly
	// clear any default security (i.e. mark the operation public).
	SetSecurity(schemes ...string)

	// AddExternalDocs attaches a single external documentation link
	// to the operation.
	AddExternalDocs(url, description string)
}

OperationContext is the surface a handler talks to when describing itself for the OpenAPI spec. The kit's handler factories implement Preparer and call AddRequest / AddResponse / setters on this type during spec collection.

type Preparer ¶

type Preparer interface {
	SetupOperation(oc OperationContext) error
}

Preparer is implemented by HTTP handlers that can describe themselves to the OpenAPI Collector. Every kit handler factory emits a value that satisfies Preparer, so the Collector can walk the registered routes and produce the spec without any annotations in code comments.

type Reflector ¶

type Reflector interface {
	// NewOperationContext returns a fresh context for the operation
	// at (method, pattern). Callers fill it via OperationContext
	// methods then pass it back to AddOperation.
	NewOperationContext(method, pattern string) (OperationContext, error)

	// AddOperation registers a fully-described operation on the spec.
	AddOperation(oc OperationContext) error

	// ApplySpecConfig applies spec-level configuration (info, servers,
	// tags, security schemes, default security, external docs).
	ApplySpecConfig(cfg SpecConfig) error

	// SpecJSON returns the assembled spec as JSON bytes.
	SpecJSON() ([]byte, error)
}

Reflector is the engine that builds an OpenAPI 3.1 spec by reflecting Go types provided through OperationContext. Forge owns this interface; the default implementation lives behind internal/swaggestimpl.

func NewReflector() Reflector

type SecurityScheme ¶

type SecurityScheme interface {
	// contains filtered or unexported methods
}

SecurityScheme is the forge representation of an OpenAPI 3.1 security scheme. Each implementation describes one of the schemes the spec supports (http+bearer, apiKey, oauth2, openIdConnect, mutualTLS).

The sealed marker method keeps consumers from defining their own — the bridge in internal/swaggestimpl needs to know every concrete type to translate it into the underlying spec.

func APIKeyCookie(cookieName string) SecurityScheme

func APIKeyHeader(headerName string) SecurityScheme

func APIKeyQuery(paramName string) SecurityScheme

func BasicAuth() SecurityScheme

func BearerJWT() SecurityScheme

func BearerToken(format string) SecurityScheme

func MutualTLSScheme() SecurityScheme

func OAuth2AuthorizationCode(authURL, tokenURL string, scopes map[string]string) SecurityScheme

func OAuth2ClientCredentials(tokenURL string, scopes map[string]string) SecurityScheme

func OAuth2Implicit(authURL string, scopes map[string]string) SecurityScheme

func OAuth2Password(tokenURL string, scopes map[string]string) SecurityScheme

func OIDCScheme(discoveryURL string) SecurityScheme

type SpecConfig ¶

type SpecConfig struct {
	Title        string
	Version      string
	Description  string
	SpecPath     string
	UIPath       string
	UIRenderer   UIRenderer
	Servers      []SpecServer
	Tags         []SpecTagInfo
	ExternalDocs *ExternalDocsInfo

	SecuritySchemes map[string]SecurityScheme
	DefaultSecurity []string
}

SpecConfig captures spec-level configuration assembled by SpecOpts. Consumed by rest.WithOpenAPI to wire the Collector and the spec/UI routes on the server.

func (c *SpecConfig) ApplyDefaults()

type SpecOpt ¶

type SpecOpt func(*SpecConfig)

SpecOpt mutates a SpecConfig as it's assembled. rest.WithOpenAPI composes a slice of these into the final config.

func DefaultSecurity(schemeNames ...string) SpecOpt

func Server(url, description string) SpecOpt

func SpecDescription(s string) SpecOpt

func SpecExternalDocs(url, description string) SpecOpt

func SpecPath(p string) SpecOpt

func SpecSecurityScheme(name string, scheme SecurityScheme) SpecOpt

func SpecTag(name, description string) SpecOpt

func SpecTitle(s string) SpecOpt

func SpecVersion(s string) SpecOpt

func UI(r UIRenderer) SpecOpt

func UIPath(p string) SpecOpt

type SpecServer ¶

type SpecServer struct {
	URL         string
	Description string
}

SpecServer is one entry in the spec's servers array.

type SpecTagInfo ¶

type SpecTagInfo struct {
	Name        string
	Description string
}

SpecTagInfo is one entry in the spec's tags array.

type UIRenderer ¶

type UIRenderer string

UIRenderer identifies which interactive documentation UI to serve. Default is SwaggerUI; alternatives are Redoc and StoplightElements (currently both fall back to Swagger UI; static assets for the alternative renderers can be plugged in later without changing the public API).

const (
	// SwaggerUI renders Swagger UI v5 with Authorize button,
	// "Try it out", and the server dropdown.
	SwaggerUI UIRenderer = "swagger-ui"

	// Redoc renders Redoc's three-pane reference layout. Read-only.
	Redoc UIRenderer = "redoc"

	// StoplightElements renders Stoplight Elements (a Redoc-style
	// reference with optional try-it-out).
	StoplightElements UIRenderer = "stoplight"
)