Documentation
¶
Overview ¶
Package respec provides the annotation API for the respec OpenAPI generator.
Everything in this package exists to be read by respec's static analyzer at build time. The builders do record what you pass them, but nothing in your program ever reads it back: at run time Handler is a pass-through and Meta does nothing. That is the point - your routing code keeps its normal shape and the documentation lives beside it instead of in comments.
r.Post("/users", respec.Handler(h.CreateUser).
Summary("Create a user").
Response(http.StatusCreated, respec.Schema(User{})).
Response(http.StatusBadRequest, respec.Desc("Invalid payload")).
Unwrap())
This package deliberately has no dependencies outside the standard library, and imports nothing from go/ast, so adding it to a web service costs nothing at run time.
Index ¶
- type GroupBuilder
- type HandlerBuilder
- func (hb *HandlerBuilder[T]) AddResponse(code int, content any) *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) AddServer(url, desc string) *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) CookieParam(name string, opts ...ParamOption) *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) Deprecate(d bool) *HandlerBuilder[T]deprecated
- func (hb *HandlerBuilder[T]) Deprecated() *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) Description(d string) *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) Extensions(ext map[string]any) *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) ExternalDocs(url, desc string) *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) HeaderParam(name string, opts ...ParamOption) *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) Hide() *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) OperationID(id string) *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) PathParam(name string, opts ...ParamOption) *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) Public() *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) QueryParam(name string, opts ...ParamOption) *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) RequestBody(obj any) *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) Response(code int, opts ...ResponseOption) *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) ResponseHeader(code int, name string, opts ...HeaderOption) *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) Security(schemeName ...string) *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) Summary(s string) *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) Tag(tags ...string) *HandlerBuilder[T]
- func (hb *HandlerBuilder[T]) Unwrap() T
- type HeaderOption
- type ParamOption
- type ResponseOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type GroupBuilder ¶ added in v0.2.1
type GroupBuilder struct {
// contains filtered or unexported fields
}
GroupBuilder carries documentation that applies to every route in a routing scope. Create one with Meta.
func Meta ¶ added in v0.2.2
func Meta(router any) *GroupBuilder
Meta attaches documentation to a routing scope. The router argument identifies the scope to the analyzer; it is not used at run time.
r.Route("/users", func(r chi.Router) {
respec.Meta(r).Tag("Users").Security("BearerAuth")
...
})
func (*GroupBuilder) Deprecate
deprecated
added in
v0.3.2
func (b *GroupBuilder) Deprecate(d bool) *GroupBuilder
Deprecate marks every route in this scope as deprecated when d is true.
Deprecated: use Deprecated, which reads better and has no redundant argument.
func (*GroupBuilder) Deprecated ¶ added in v1.0.0
func (b *GroupBuilder) Deprecated() *GroupBuilder
Deprecated marks every route in this scope as deprecated.
func (*GroupBuilder) Public ¶ added in v1.0.0
func (b *GroupBuilder) Public() *GroupBuilder
Public clears security inherited from enclosing scopes.
func (*GroupBuilder) Security ¶ added in v0.2.1
func (b *GroupBuilder) Security(schemeName ...string) *GroupBuilder
Security names the security schemes every route in this scope requires.
func (*GroupBuilder) Tag ¶ added in v0.2.1
func (b *GroupBuilder) Tag(tags ...string) *GroupBuilder
Tag adds tags to every route in this scope.
type HandlerBuilder ¶ added in v0.2.9
type HandlerBuilder[T any] struct { // contains filtered or unexported fields }
HandlerBuilder carries documentation for a single operation. Create one with Handler and finish with Unwrap.
func Handler ¶ added in v0.2.1
func Handler[T any](handler T) *HandlerBuilder[T]
Handler wraps a handler so it can be documented. The handler's type is preserved, so Unwrap returns exactly what you passed in and any router accepts it.
func (*HandlerBuilder[T]) AddResponse ¶ added in v0.3.2
func (hb *HandlerBuilder[T]) AddResponse(code int, content any) *HandlerBuilder[T]
AddResponse declares a response from either a value (used as the schema) or a string (used as the description).
Response is the fuller form and can express both at once; AddResponse remains because it reads well for the common case.
func (*HandlerBuilder[T]) AddServer ¶ added in v0.3.2
func (hb *HandlerBuilder[T]) AddServer(url, desc string) *HandlerBuilder[T]
AddServer adds an operation-level server URL.
func (*HandlerBuilder[T]) CookieParam ¶ added in v1.0.0
func (hb *HandlerBuilder[T]) CookieParam(name string, opts ...ParamOption) *HandlerBuilder[T]
CookieParam declares a cookie parameter.
func (*HandlerBuilder[T]) Deprecate
deprecated
added in
v0.3.2
func (hb *HandlerBuilder[T]) Deprecate(d bool) *HandlerBuilder[T]
Deprecate marks the operation as deprecated when d is true.
Deprecated: use Deprecated, which reads better and has no redundant argument.
func (*HandlerBuilder[T]) Deprecated ¶ added in v1.0.0
func (hb *HandlerBuilder[T]) Deprecated() *HandlerBuilder[T]
Deprecated marks the operation as deprecated.
func (*HandlerBuilder[T]) Description ¶ added in v0.2.9
func (hb *HandlerBuilder[T]) Description(d string) *HandlerBuilder[T]
Description sets the operation's long description.
func (*HandlerBuilder[T]) Extensions ¶ added in v0.3.5
func (hb *HandlerBuilder[T]) Extensions(ext map[string]any) *HandlerBuilder[T]
Extensions adds vendor extension fields. Keys should begin with "x-".
func (*HandlerBuilder[T]) ExternalDocs ¶ added in v0.3.2
func (hb *HandlerBuilder[T]) ExternalDocs(url, desc string) *HandlerBuilder[T]
ExternalDocs links to documentation hosted elsewhere.
func (*HandlerBuilder[T]) HeaderParam ¶ added in v1.0.0
func (hb *HandlerBuilder[T]) HeaderParam(name string, opts ...ParamOption) *HandlerBuilder[T]
HeaderParam declares a header parameter.
func (*HandlerBuilder[T]) Hide ¶ added in v1.0.0
func (hb *HandlerBuilder[T]) Hide() *HandlerBuilder[T]
Hide omits this operation from the generated spec. Use it for internal or debug endpoints that should not appear in published documentation.
func (*HandlerBuilder[T]) OperationID ¶ added in v0.3.2
func (hb *HandlerBuilder[T]) OperationID(id string) *HandlerBuilder[T]
OperationID sets the operation's unique identifier, used by client generators.
func (*HandlerBuilder[T]) PathParam ¶ added in v1.0.0
func (hb *HandlerBuilder[T]) PathParam(name string, opts ...ParamOption) *HandlerBuilder[T]
PathParam declares a path parameter. Path parameters are always required.
func (*HandlerBuilder[T]) Public ¶ added in v1.0.0
func (hb *HandlerBuilder[T]) Public() *HandlerBuilder[T]
Public clears any security requirement inherited from the enclosing group. Use it for endpoints such as login or health checks that sit inside an otherwise authenticated group.
func (*HandlerBuilder[T]) QueryParam ¶ added in v1.0.0
func (hb *HandlerBuilder[T]) QueryParam(name string, opts ...ParamOption) *HandlerBuilder[T]
QueryParam declares a query parameter.
func (*HandlerBuilder[T]) RequestBody ¶ added in v0.3.2
func (hb *HandlerBuilder[T]) RequestBody(obj any) *HandlerBuilder[T]
RequestBody declares the request body schema from a value of the body's type.
func (*HandlerBuilder[T]) Response ¶ added in v1.0.0
func (hb *HandlerBuilder[T]) Response(code int, opts ...ResponseOption) *HandlerBuilder[T]
Response declares a response. Options compose, so a response can carry both a schema and a description:
.Response(400, respec.Schema(APIError{}), respec.Desc("Validation failed"))
func (*HandlerBuilder[T]) ResponseHeader ¶ added in v0.3.2
func (hb *HandlerBuilder[T]) ResponseHeader(code int, name string, opts ...HeaderOption) *HandlerBuilder[T]
ResponseHeader declares a header returned with a given response code.
func (*HandlerBuilder[T]) Security ¶ added in v0.2.9
func (hb *HandlerBuilder[T]) Security(schemeName ...string) *HandlerBuilder[T]
Security names the security schemes this operation requires, replacing any inherited from the enclosing group.
func (*HandlerBuilder[T]) Summary ¶ added in v0.2.9
func (hb *HandlerBuilder[T]) Summary(s string) *HandlerBuilder[T]
Summary sets the operation's one-line summary.
func (*HandlerBuilder[T]) Tag ¶ added in v0.2.9
func (hb *HandlerBuilder[T]) Tag(tags ...string) *HandlerBuilder[T]
Tag adds tags, replacing any inherited from the enclosing group.
func (*HandlerBuilder[T]) Unwrap ¶ added in v0.2.9
func (hb *HandlerBuilder[T]) Unwrap() T
Unwrap returns the original handler. It must be the last call in the chain.
type HeaderOption ¶ added in v1.0.0
type HeaderOption func(*headerSpec)
HeaderOption configures a response header.
func HeaderDoc ¶ added in v1.0.0
func HeaderDoc(s string) HeaderOption
HeaderDoc sets a response header's description.
func HeaderType ¶ added in v1.0.0
func HeaderType(t string) HeaderOption
HeaderType sets a response header's primitive type. The default is string.
type ParamOption ¶ added in v1.0.0
type ParamOption func(*paramSpec)
ParamOption configures a parameter.
func DeprecatedParam ¶ added in v1.0.0
func DeprecatedParam() ParamOption
DeprecatedParam marks a parameter as deprecated.
func Example ¶ added in v1.0.0
func Example(v string) ParamOption
Example sets a parameter's example value.
func Type ¶ added in v1.0.0
func Type(t string) ParamOption
Type sets a parameter's primitive type: string, integer, number, or boolean. The default is string.
type ResponseOption ¶ added in v1.0.0
type ResponseOption func(*responseSpec)
ResponseOption configures a response declared with Response.
func Schema ¶ added in v1.0.0
func Schema(v any) ResponseOption
Schema sets a response's body schema from a value of the body's type.
Source Files