oas

package
v0.1.5 Latest Latest
Warning

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

 Go to latest Published: Jan 24, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Inject 

func Inject(opts []openapi.HandlerOption, def RouteDef) []openapi.HandlerOption

Inject converts a RouteDef into route options.

func Key 

func Key(method, path string) string

Key builds the Spec key.

Types

type Builder 

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

Builder helps you build a Spec without manually typing keys like "GET /users/:id".

Example: 

spec := oas.NewSpec().
	Group("/", func(s *oas.SpecBuilder) {
		s.GET("/users").Tags("Users").Res([]User{}).OK()
		s.POST("/users").Tags("Users").Req(CreateUser{}).Res(struct{}{}).Status(http.StatusCreated)
	})
	Spec()

NOTE: This builder does not try to infer schemas from handlers. You still declare Req/Res schema samples here.

func NewSpec 

func NewSpec() *Builder

func (*Builder) Group 

func (b *Builder) Group(prefix string, fn func(s *SpecBuilder)) *Builder

Group helps apply a path prefix to multiple routes.

func (*Builder) GroupTags 

func (b *Builder) GroupTags(prefix string, tags []string, fn func(s *SpecBuilder)) *Builder

GroupTags is like Group, but also applies default tags to every route defined in the group.

func (*Builder) Spec 

func (b *Builder) Spec() Spec

Spec returns the built Spec.

func (*Builder) With 

func (b *Builder) With(s Spec) *Builder

With preloads an existing spec (merged; def from b wins on conflict).

type EchoGroup 

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

func (*EchoGroup) DELETE 

func (g *EchoGroup) DELETE(path string, h echolib.HandlerFunc, opts ...echoadapter.HandlerOption)

func (*EchoGroup) GET 

func (g *EchoGroup) GET(path string, h echolib.HandlerFunc, opts ...echoadapter.HandlerOption)

func (*EchoGroup) Handle 

func (g *EchoGroup) Handle(method, path string, h echolib.HandlerFunc, opts ...echoadapter.HandlerOption)

func (*EchoGroup) PATCH 

func (g *EchoGroup) PATCH(path string, h echolib.HandlerFunc, opts ...echoadapter.HandlerOption)

func (*EchoGroup) POST 

func (g *EchoGroup) POST(path string, h echolib.HandlerFunc, opts ...echoadapter.HandlerOption)

func (*EchoGroup) PUT 

func (g *EchoGroup) PUT(path string, h echolib.HandlerFunc, opts ...echoadapter.HandlerOption)

type EchoRouter 

type EchoRouter struct {
	Base *echoadapter.Router
	Spec Spec
}

EchoRouter wraps the echo adapter Router and injects options from Spec automatically.

func NewEchoRouter 

func NewEchoRouter(base *echoadapter.Router, spec Spec) *EchoRouter

func (*EchoRouter) DELETE 

func (r *EchoRouter) DELETE(path string, h echolib.HandlerFunc, opts ...echoadapter.HandlerOption)

func (*EchoRouter) GET 

func (r *EchoRouter) GET(path string, h echolib.HandlerFunc, opts ...echoadapter.HandlerOption)

func (*EchoRouter) Group 

func (r *EchoRouter) Group(prefix string, opts ...echoadapter.HandlerOption) *EchoGroup

func (*EchoRouter) Handle 

func (r *EchoRouter) Handle(method, path string, h echolib.HandlerFunc, opts ...echoadapter.HandlerOption)

func (*EchoRouter) PATCH 

func (r *EchoRouter) PATCH(path string, h echolib.HandlerFunc, opts ...echoadapter.HandlerOption)

func (*EchoRouter) POST 

func (r *EchoRouter) POST(path string, h echolib.HandlerFunc, opts ...echoadapter.HandlerOption)

func (*EchoRouter) PUT 

func (r *EchoRouter) PUT(path string, h echolib.HandlerFunc, opts ...echoadapter.HandlerOption)

func (*EchoRouter) Routes 

func (r *EchoRouter) Routes() []openapi.RouteMeta

type FiberGroup 

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

func (*FiberGroup) DELETE 

func (g *FiberGroup) DELETE(path string, h fiberlib.Handler, opts ...fiberadapter.HandlerOption)

func (*FiberGroup) GET 

func (g *FiberGroup) GET(path string, h fiberlib.Handler, opts ...fiberadapter.HandlerOption)

func (*FiberGroup) Handle 

func (g *FiberGroup) Handle(method, path string, h fiberlib.Handler, opts ...fiberadapter.HandlerOption)

func (*FiberGroup) PATCH 

func (g *FiberGroup) PATCH(path string, h fiberlib.Handler, opts ...fiberadapter.HandlerOption)

func (*FiberGroup) POST 

func (g *FiberGroup) POST(path string, h fiberlib.Handler, opts ...fiberadapter.HandlerOption)

func (*FiberGroup) PUT 

func (g *FiberGroup) PUT(path string, h fiberlib.Handler, opts ...fiberadapter.HandlerOption)

type FiberRouter 

type FiberRouter struct {
	Base *fiberadapter.Router
	Spec Spec
}

FiberRouter wraps the fiber adapter Router and injects options from Spec automatically.

func NewFiberRouter 

func NewFiberRouter(base *fiberadapter.Router, spec Spec) *FiberRouter

func (*FiberRouter) DELETE 

func (r *FiberRouter) DELETE(path string, h fiberlib.Handler, opts ...fiberadapter.HandlerOption)

func (*FiberRouter) GET 

func (r *FiberRouter) GET(path string, h fiberlib.Handler, opts ...fiberadapter.HandlerOption)

func (*FiberRouter) Group 

func (r *FiberRouter) Group(prefix string, opts ...fiberadapter.HandlerOption) *FiberGroup

func (*FiberRouter) Handle 

func (r *FiberRouter) Handle(method, path string, h fiberlib.Handler, opts ...fiberadapter.HandlerOption)

func (*FiberRouter) PATCH 

func (r *FiberRouter) PATCH(path string, h fiberlib.Handler, opts ...fiberadapter.HandlerOption)

func (*FiberRouter) POST 

func (r *FiberRouter) POST(path string, h fiberlib.Handler, opts ...fiberadapter.HandlerOption)

func (*FiberRouter) PUT 

func (r *FiberRouter) PUT(path string, h fiberlib.Handler, opts ...fiberadapter.HandlerOption)

func (*FiberRouter) Routes 

func (r *FiberRouter) Routes() []openapi.RouteMeta

type GinGroup 

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

GinGroup provides grouping with prefix + shared options, while preserving Spec injection.

func (*GinGroup) DELETE 

func (g *GinGroup) DELETE(path string, h ginlib.HandlerFunc, opts ...ginadapter.HandlerOption)

func (*GinGroup) GET 

func (g *GinGroup) GET(path string, h ginlib.HandlerFunc, opts ...ginadapter.HandlerOption)

func (*GinGroup) Handle 

func (g *GinGroup) Handle(method, path string, h ginlib.HandlerFunc, opts ...ginadapter.HandlerOption)

func (*GinGroup) PATCH 

func (g *GinGroup) PATCH(path string, h ginlib.HandlerFunc, opts ...ginadapter.HandlerOption)

func (*GinGroup) POST 

func (g *GinGroup) POST(path string, h ginlib.HandlerFunc, opts ...ginadapter.HandlerOption)

func (*GinGroup) PUT 

func (g *GinGroup) PUT(path string, h ginlib.HandlerFunc, opts ...ginadapter.HandlerOption)

type GinRouter 

type GinRouter struct {
	Base *ginadapter.Router
	Spec Spec
}

GinRouter wraps the gin adapter Router and injects options from Spec automatically.

func NewGinRouter 

func NewGinRouter(base *ginadapter.Router, spec Spec) *GinRouter

func (*GinRouter) DELETE 

func (r *GinRouter) DELETE(path string, h ginlib.HandlerFunc, opts ...ginadapter.HandlerOption)

func (*GinRouter) GET 

func (r *GinRouter) GET(path string, h ginlib.HandlerFunc, opts ...ginadapter.HandlerOption)

func (*GinRouter) Group 

func (r *GinRouter) Group(prefix string, opts ...ginadapter.HandlerOption) *GinGroup

func (*GinRouter) Handle 

func (r *GinRouter) Handle(method, path string, h ginlib.HandlerFunc, opts ...ginadapter.HandlerOption)

func (*GinRouter) PATCH 

func (r *GinRouter) PATCH(path string, h ginlib.HandlerFunc, opts ...ginadapter.HandlerOption)

func (*GinRouter) POST 

func (r *GinRouter) POST(path string, h ginlib.HandlerFunc, opts ...ginadapter.HandlerOption)

func (*GinRouter) PUT 

func (r *GinRouter) PUT(path string, h ginlib.HandlerFunc, opts ...ginadapter.HandlerOption)

func (*GinRouter) Routes 

func (r *GinRouter) Routes() []openapi.RouteMeta

type RouteBuilder 

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

RouteBuilder builds a single route definition.

func (*RouteBuilder) Created 

func (r *RouteBuilder) Created() *RouteBuilder

Created is shorthand for Status(http.StatusCreated).

func (*RouteBuilder) Done 

func (r *RouteBuilder) Done() *RouteBuilder

Done commits the current definition without changing status. Use this if you only want tags/security/query and no schema.

func (*RouteBuilder) Headers 

func (r *RouteBuilder) Headers(params ...openapi.HeaderParam) *RouteBuilder

func (*RouteBuilder) MultipartUpload 

func (r *RouteBuilder) MultipartUpload(fileField string, fields ...openapi.MultipartField) *RouteBuilder

MultipartUpload declares a multipart/form-data request body with a required file field.

Example: 

s.POST("/users/upload").MultipartUpload("file", openapi.MultipartField{Name: "note", Type: openapi.ParamString}).Res(map[string]string{}).OK()

Under the hood this uses openapi.MultipartFile marker so the OpenAPI builder can render multipart/form-data with binary file part.

func (*RouteBuilder) NoContent 

func (r *RouteBuilder) NoContent() *RouteBuilder

NoContent is shorthand for Status(http.StatusNoContent).

func (*RouteBuilder) OK 

func (r *RouteBuilder) OK() *RouteBuilder

OK is shorthand for Status(http.StatusOK).

func (*RouteBuilder) Query 

func (r *RouteBuilder) Query(params ...openapi.QueryParam) *RouteBuilder

func (*RouteBuilder) Req 

func (r *RouteBuilder) Req(schema any) *RouteBuilder

func (*RouteBuilder) Res 

func (r *RouteBuilder) Res(schema any) *RouteBuilder

func (*RouteBuilder) Responses 

func (r *RouteBuilder) Responses(specs ...openapi.ResponseSpec) *RouteBuilder

Responses appends additional response specs (like 400/500 error shape).

func (*RouteBuilder) Security 

func (r *RouteBuilder) Security(sec *openapi3.SecurityRequirement) *RouteBuilder

func (*RouteBuilder) Status 

func (r *RouteBuilder) Status(status int) *RouteBuilder

func (*RouteBuilder) Tags 

func (r *RouteBuilder) Tags(tags ...string) *RouteBuilder

type RouteDef 

type RouteDef struct {
	Tags         []string
	Security     *openapi3.SecurityRequirement
	QueryParams  []openapi.QueryParam
	HeaderParams []openapi.HeaderParam

	ReqSchema any
	ResSchema any
	Status    int

	// Optional extra responses (errors, alternate status codes)
	Responses []openapi.ResponseSpec
}

RouteDef is a config-only description of an endpoint.

This is the "SpringBoot-like" mode: keep handlers/routes clean, put OpenAPI request/response schema + tags/security/query definition in one config place.

Note: request/response schema inference is not possible from plain Go handlers, so you still need to declare them here (or omit them).

If ReqSchema/ResSchema is nil, schema isn't declared.

type Router 

type Router struct {
	Base *openapi.Router
	Spec Spec
}

Router wraps an openapi.Router and injects options from Spec automatically. Your route registrations can stay as plain GET/POST/... without JSONRoute/With... per route.

func NewHttpRouter 

func NewHttpRouter(base *openapi.Router, spec Spec) *Router

func (*Router) DELETE 

func (r *Router) DELETE(path string, h http.HandlerFunc, opts ...openapi.HandlerOption)

func (*Router) GET 

func (r *Router) GET(path string, h http.HandlerFunc, opts ...openapi.HandlerOption)

func (*Router) Group 

func (r *Router) Group(prefix string, opts ...openapi.HandlerOption) *openapi.Group

func (*Router) Handle 

func (r *Router) Handle(method, path string, h http.HandlerFunc, opts ...openapi.HandlerOption)

func (*Router) PATCH 

func (r *Router) PATCH(path string, h http.HandlerFunc, opts ...openapi.HandlerOption)

func (*Router) POST 

func (r *Router) POST(path string, h http.HandlerFunc, opts ...openapi.HandlerOption)

func (*Router) PUT 

func (r *Router) PUT(path string, h http.HandlerFunc, opts ...openapi.HandlerOption)

func (*Router) Routes 

func (r *Router) Routes() []openapi.RouteMeta

func (*Router) ServeHTTP 

func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)

type Spec 

type Spec map[string]RouteDef

Spec maps method+path to its OpenAPI definition. Key format: "METHOD /path".

type SpecBuilder 

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

SpecBuilder is a scoped builder that can apply a prefix.

func (*SpecBuilder) DELETE 

func (s *SpecBuilder) DELETE(p string) *RouteBuilder

func (*SpecBuilder) GET 

func (s *SpecBuilder) GET(p string) *RouteBuilder

func (*SpecBuilder) PATCH 

func (s *SpecBuilder) PATCH(p string) *RouteBuilder

func (*SpecBuilder) POST 

func (s *SpecBuilder) POST(p string) *RouteBuilder

func (*SpecBuilder) PUT 

func (s *SpecBuilder) PUT(p string) *RouteBuilder

func (*SpecBuilder) WithTags 

func (s *SpecBuilder) WithTags(tags ...string) *SpecBuilder

WithTags sets default tags for all routes built from this builder.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.