Documentation
¶
Overview ¶
Package specs provides stable OpenAPI registry utilities and endpoint constants.
Index ¶
- Constants
- Variables
- 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)
- type Components
- type Info
- type MediaType
- type Operation
- type Parameter
- type Registry
- func (r *Registry) OpenAPI() ([]byte, error)
- 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) SetServers(servers []Server)
- 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 RegisterSchemaFrom ¶ added in v2.1.0
func RegisterSchemaFrom[T any](registry *Registry, name string, opts SchemaOptions) error
RegisterSchemaFrom generates and registers an OpenAPI schema component.
func SchemaFrom ¶ added in v2.1.0
func SchemaFrom[T any](opts SchemaOptions) (map[string]any, error)
SchemaFrom generates an OpenAPI schema from T.
func SchemaFromType ¶ added in v2.1.0
SchemaFromType generates an OpenAPI schema from a Go type.
Types ¶
type Components ¶ added in v2.1.0
type Components struct {
Schemas map[string]map[string]any
Responses map[string]Response
SecuritySchemes map[string]SecurityScheme
}
Components describes reusable OpenAPI components.
type MediaType ¶ added in v2.1.0
type MediaType struct {
Schema map[string]any
SchemaRef string
Example any
Examples map[string]any
}
MediaType describes OpenAPI media type metadata.
type Operation ¶
type Operation struct {
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 ¶ added in v2.1.0
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 (*Registry) RegisterResponse ¶ added in v2.1.0
RegisterResponse registers or replaces a reusable response component.
func (*Registry) RegisterSchema ¶ added in v2.1.0
RegisterSchema registers or replaces a reusable schema component.
func (*Registry) RegisterSecurityScheme ¶ added in v2.1.0
func (r *Registry) RegisterSecurityScheme(name string, scheme SecurityScheme)
RegisterSecurityScheme registers or replaces a reusable security scheme.
func (*Registry) SetComponents ¶ added in v2.1.0
func (r *Registry) SetComponents(components Components)
SetComponents replaces reusable OpenAPI components.
func (*Registry) SetServers ¶
SetServers replaces the server list.
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.
type SchemaOptions ¶ added in v2.1.0
type SchemaOptions struct {
RefPrefix string
}
SchemaOptions configures schema generation from Go types.
type SecurityRequirement ¶ added in v2.1.0
SecurityRequirement describes an operation security requirement.