Documentation
¶
Overview ¶
Package specs provides stable OpenAPI registry utilities and endpoint constants. The registry supports deterministic code-first operation registration, reusable components, operation-level security requirements, and top-level security defaults for generated OpenAPI documents. NewRegistry preserves OpenAPI 3.0 output, while NewRegistryWithOptions can opt services into OpenAPI 3.1 output. Schema helpers cover nullable fields, examples, enums, reusable references, media examples, and reusable Problem Details response components.
Index ¶
- Constants
- Variables
- func HTTPProblemResponseName(status int) string
- func NullableSchema(schema map[string]any) map[string]any
- func ProblemSchema() map[string]any
- func RegisterHTTPProblemResponses(registry *Registry, statuses ...int)
- func RegisterProblemCatalog(registry *Registry, catalog *httpx.ProblemCatalog)
- func RegisterSchemaFrom[T any](registry *Registry, name string, opts SchemaOptions) error
- func SchemaFrom[T any](opts SchemaOptions) (map[string]any, error)
- func SchemaFromType(typ reflect.Type, opts SchemaOptions) (map[string]any, error)
- func SchemaRef(ref string) map[string]any
- func SchemaWithEnum(schema map[string]any, values ...any) map[string]any
- func SchemaWithExample(schema map[string]any, example any) map[string]any
- type Components
- type Example
- type Info
- type MediaType
- type OpenAPIVersion
- type Operation
- type Parameter
- type Registry
- func (r *Registry) OpenAPI() ([]byte, error)
- func (r *Registry) Operations() []Operation
- func (r *Registry) Register(op Operation)
- func (r *Registry) RegisterResponse(name string, response Response)
- func (r *Registry) RegisterSchema(name string, schema map[string]any)
- func (r *Registry) RegisterSecurityScheme(name string, scheme SecurityScheme)
- func (r *Registry) SetComponents(components Components)
- func (r *Registry) SetSecurity(requirements []SecurityRequirement)
- func (r *Registry) SetServers(servers []Server)
- type RegistryOptions
- type RegistryProvider
- type RequestBody
- type Response
- type SchemaOptions
- type SecurityRequirement
- type SecurityScheme
- type Server
Constants ¶
const ( // Health check endpoints Livez = "/livez" Readyz = "/readyz" Healthz = "/healthz" Health = "/health" HealthDetailed = "/health/detailed" // Documentation endpoints Docs = "/docs" DocsOpenAPI = "/docs/openapi.json" DocsVersion = "/docs/version" DocsInfo = "/docs/info" // System endpoints Version = "/version" // Metrics endpoint (Prometheus) Metrics = "/metrics" // Pprof endpoints for runtime profiling. PprofIndex = "/debug/pprof/" PprofCmdline = "/debug/pprof/cmdline" PprofProfile = "/debug/pprof/profile" PprofSymbol = "/debug/pprof/symbol" PprofTrace = "/debug/pprof/trace" )
System endpoints for health checks and documentation
Variables ¶
var AllEndpoints = struct { Health interface{} Docs interface{} System interface{} }{ Health: HealthEndpoints, Docs: DocsEndpoints, System: SystemEndpoints, }
AllEndpoints groups all available endpoints
var DocsEndpoints = struct { Docs string OpenAPI string Version string Info string }{ Docs: Docs, OpenAPI: DocsOpenAPI, Version: DocsVersion, Info: DocsInfo, }
DocsEndpoints groups all documentation-related endpoints
var HealthEndpoints = struct { Livez string Readyz string Healthz string Health string HealthDetailed string }{ Livez: Livez, Readyz: Readyz, Healthz: Healthz, Health: Health, HealthDetailed: HealthDetailed, }
HealthEndpoints groups all health-related endpoints
var PprofEndpoints = struct { Index string Cmdline string Profile string Symbol string Trace string }{ Index: PprofIndex, Cmdline: PprofCmdline, Profile: PprofProfile, Symbol: PprofSymbol, Trace: PprofTrace, }
PprofEndpoints groups all profiling endpoints.
var SystemEndpoints = struct { Version string }{ Version: Version, }
SystemEndpoints groups all system-related endpoints
Functions ¶
func HTTPProblemResponseName ¶
HTTPProblemResponseName returns the conventional response component name for an HTTP status.
func NullableSchema ¶
NullableSchema returns a copy of schema marked nullable.
func ProblemSchema ¶
ProblemSchema returns the reusable OpenAPI schema for RFC 9457 Problem Details.
func RegisterHTTPProblemResponses ¶
RegisterHTTPProblemResponses registers reusable Problem Details response components by HTTP status.
func RegisterProblemCatalog ¶
func RegisterProblemCatalog(registry *Registry, catalog *httpx.ProblemCatalog)
RegisterProblemCatalog registers reusable Problem Details schemas and responses.
func RegisterSchemaFrom ¶
func RegisterSchemaFrom[T any](registry *Registry, name string, opts SchemaOptions) error
RegisterSchemaFrom generates and registers an OpenAPI schema component.
func SchemaFrom ¶
func SchemaFrom[T any](opts SchemaOptions) (map[string]any, error)
SchemaFrom generates an OpenAPI schema from T.
func SchemaFromType ¶
SchemaFromType generates an OpenAPI schema from a Go type.
func SchemaWithEnum ¶
SchemaWithEnum returns a copy of schema with OpenAPI enum values.
Types ¶
type Components ¶
type Components struct {
Schemas map[string]map[string]any
Responses map[string]Response
SecuritySchemes map[string]SecurityScheme
}
Components describes reusable OpenAPI components.
type Example ¶
type Example struct {
Summary string `json:"summary,omitempty"`
Description string `json:"description,omitempty"`
Value any `json:"value,omitempty"`
ExternalValue string `json:"externalValue,omitempty"`
}
Example describes a reusable OpenAPI example object.
type MediaType ¶
type MediaType struct {
Schema map[string]any
SchemaRef string
Example any
Examples map[string]any
}
MediaType describes OpenAPI media type metadata.
type OpenAPIVersion ¶
type OpenAPIVersion string
OpenAPIVersion identifies the OpenAPI document version emitted by a Registry.
const ( // OpenAPIVersion30 is the default version emitted by NewRegistry. OpenAPIVersion30 OpenAPIVersion = "3.0.0" // OpenAPIVersion31 enables OpenAPI 3.1 output for services that opt in. OpenAPIVersion31 OpenAPIVersion = "3.1.0" )
type Operation ¶
type Operation struct {
OperationID string
Method string
Path string
Summary string
Description string
Tags []string
Deprecated bool
Sunset string
Parameters []Parameter
Security []SecurityRequirement
Scopes []string
RequestBody *RequestBody
Responses map[int]Response
Extensions map[string]any
}
Operation describes an API operation for registry usage.
type Parameter ¶
type Parameter struct {
Name string
In string
Description string
Required bool
Schema map[string]any
}
Parameter describes an OpenAPI operation parameter.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry collects operations and produces a minimal OpenAPI document.
func NewRegistry ¶
NewRegistry constructs an OpenAPI registry with the provided info.
func NewRegistryWithOptions ¶
func NewRegistryWithOptions(info Info, opts RegistryOptions) *Registry
NewRegistryWithOptions constructs an OpenAPI registry with explicit options.
func (*Registry) Operations ¶
Operations returns the registered operations in deterministic OpenAPI order.
func (*Registry) RegisterResponse ¶
RegisterResponse registers or replaces a reusable response component.
func (*Registry) RegisterSchema ¶
RegisterSchema registers or replaces a reusable schema component.
func (*Registry) RegisterSecurityScheme ¶
func (r *Registry) RegisterSecurityScheme(name string, scheme SecurityScheme)
RegisterSecurityScheme registers or replaces a reusable security scheme.
func (*Registry) SetComponents ¶
func (r *Registry) SetComponents(components Components)
SetComponents replaces reusable OpenAPI components.
func (*Registry) SetSecurity ¶
func (r *Registry) SetSecurity(requirements []SecurityRequirement)
SetSecurity replaces top-level OpenAPI security requirements.
func (*Registry) SetServers ¶
SetServers replaces the server list.
type RegistryOptions ¶
type RegistryOptions struct {
OpenAPIVersion OpenAPIVersion
}
RegistryOptions configures OpenAPI registry behavior.
type RegistryProvider ¶
type RegistryProvider struct {
// contains filtered or unexported fields
}
RegistryProvider adapts an OpenAPI registry to the DocsProvider interface.
func NewRegistryProvider ¶
func NewRegistryProvider(registry *Registry, info ports.DocsInfo, openAPIPath string) *RegistryProvider
NewRegistryProvider creates a DocsProvider backed by a registry.
func (*RegistryProvider) GetHTML ¶
func (p *RegistryProvider) GetHTML() (string, error)
GetHTML returns a basic Swagger UI page pointing at the registry OpenAPI JSON.
func (*RegistryProvider) GetInfo ¶
func (p *RegistryProvider) GetInfo() ports.DocsInfo
GetInfo returns the registry info.
func (*RegistryProvider) GetOpenAPI ¶
func (p *RegistryProvider) GetOpenAPI() ([]byte, error)
GetOpenAPI returns the JSON OpenAPI document from the registry.
func (*RegistryProvider) GetVersion ¶
func (p *RegistryProvider) GetVersion() (string, error)
GetVersion returns the registry version.
type RequestBody ¶
type RequestBody struct {
Description string
Required bool
ContentTypes []string
Content map[string]MediaType
}
RequestBody describes request content metadata.
type Response ¶
type Response struct {
Description string
ContentTypes []string
Content map[string]MediaType
Ref string
}
Response describes response content metadata.
func HTTPProblemResponseRef ¶
HTTPProblemResponseRef returns a response reference for an HTTP Problem response component.
func ProblemResponse ¶
ProblemResponse returns a reusable Problem Details response object.
func ValidationProblemResponse ¶
ValidationProblemResponse returns a reusable validation Problem Details response object.
type SchemaOptions ¶
type SchemaOptions struct {
RefPrefix string
}
SchemaOptions configures schema generation from Go types.
type SecurityRequirement ¶
SecurityRequirement describes an OpenAPI security requirement.
Source Files