specs

package
v2.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 2, 2026 License: Apache-2.0 Imports: 10 Imported by: 1

Documentation

Overview

Package specs provides stable OpenAPI registry utilities and endpoint constants.

Index

Constants

View Source
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

View Source
var AllEndpoints = struct {
	Health interface{}
	Docs   interface{}
	System interface{}
}{
	Health: HealthEndpoints,
	Docs:   DocsEndpoints,
	System: SystemEndpoints,
}

AllEndpoints groups all available endpoints

View Source
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

View Source
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

View Source
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.

View Source
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

func SchemaFromType(typ reflect.Type, opts SchemaOptions) (map[string]any, error)

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 Info

type Info struct {
	Title       string
	Description string
	Version     string
}

Info describes OpenAPI metadata for a registry.

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

func NewRegistry(info Info) *Registry

NewRegistry constructs an OpenAPI registry with the provided info.

func (*Registry) OpenAPI

func (r *Registry) OpenAPI() ([]byte, error)

OpenAPI returns a JSON-encoded OpenAPI 3.0 document.

func (*Registry) Register

func (r *Registry) Register(op Operation)

Register registers an operation in the registry.

func (*Registry) RegisterResponse added in v2.1.0

func (r *Registry) RegisterResponse(name string, response Response)

RegisterResponse registers or replaces a reusable response component.

func (*Registry) RegisterSchema added in v2.1.0

func (r *Registry) RegisterSchema(name string, schema map[string]any)

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

func (r *Registry) SetServers(servers []Server)

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

type SecurityRequirement struct {
	Name   string
	Scopes []string
}

SecurityRequirement describes an operation security requirement.

type SecurityScheme added in v2.1.0

type SecurityScheme struct {
	Type             string
	Description      string
	Name             string
	In               string
	Scheme           string
	BearerFormat     string
	OpenIDConnectURL string
	Flows            map[string]any
}

SecurityScheme describes a reusable OpenAPI security scheme.

type Server

type Server struct {
	URL         string
	Description string
}

Server describes an OpenAPI server entry.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL