spec

Documentation

Index

• func CreateReflector(opts *ReflectorOptions) *openapi3.Reflector
• type Error
  • func Err(code int) *Error
  • func (e *Error) Data(data *JSONObject) *Error
  • func (e *Error) Message(msg string) *Error
• type JSONObject
• type Method
• type Opt
  • func WithBody(body any) Opt
  • func WithDescription(description string) Opt
  • func WithErrBadRequest(message ...string) Opt
  • func WithErrNotFound(message ...string) Opt
  • func WithError(errorCode int, message ...string) Opt
  • func WithForbidden(message ...string) Opt
  • func WithInternalError(message ...string) Opt
  • func WithMethod(m Method) Opt
  • func WithOriginalPath(p string) Opt
  • func WithParam(loc ParamLocation, title string, paramType ...string) Opt
  • func WithParams(params []*Parameter) Opt
  • func WithPath(p string) Opt
  • func WithPathPrefix(p string) Opt
  • func WithResponse(body any, code ...int) Opt
  • func WithSummary(summary string) Opt
  • func WithTags(tags ...string) Opt
  • func WithUnauthorized(message ...string) Opt
• type ParamLocation
• type Parameter
• type ReflectorOptions
• type Response
• type Spec
  • func Delete(routePath string, res any, opts ...Opt) *Spec
  • func Get(routePath string, res any, opts ...Opt) *Spec
  • func Of(opts ...Opt) *Spec
  • func Patch(routePath string, body any, res any, opts ...Opt) *Spec
  • func Post(routePath string, body any, res any, opts ...Opt) *Spec
  • func Put(routePath string, body any, res any, opts ...Opt) *Spec
  • func (s *Spec) Build(ref *openapi3.Reflector) error
  • func (s *Spec) FullPath() string
  • func (s *Spec) FullRouterPath() string
  • func (s *Spec) With(opts ...Opt) *Spec
  • func (s *Spec) WithAPIAuth() *Spec
  • func (s *Spec) WithAuth() *Spec
  • func (s *Spec) WithQueryObject(obj any) *Spec
  • func (s *Spec) WithTags(tags ...string) *Spec

Functions

func CreateReflector

func CreateReflector(opts *ReflectorOptions) *openapi3.Reflector

CreateReflector ...

Types

type Error

type Error struct {
	Code           int         `json:"code,omitempty" yaml:"code,omitempty"`
	Msg            string      `json:"message,omitempty" yaml:"message,omitempty"`
	AdditionalData *JSONObject `json:"data,omitempty" yaml:"data,omitempty"`
}

Error is data object for returning errors

func Err

func Err(code int) *Error

Err is the constructor for Error

func (*Error) Data

func (e *Error) Data(data *JSONObject) *Error

Data sets the data property for Error

func (*Error) Message

func (e *Error) Message(msg string) *Error

Message sets the message for Error

type JSONObject

type JSONObject map[string]interface{}

JSONObject represents a map[string]interface{} shorthand

type Method

type Method string

Method is a HTTP method

const (
	MethodGet    Method = http.MethodGet
	MethodPost   Method = http.MethodPost
	MethodPut    Method = http.MethodPut
	MethodPatch  Method = http.MethodPatch
	MethodDelete Method = http.MethodDelete
)

Method values (straight from the net/http)

type Opt

type Opt func(s *Spec) error

Opt defines an option function for Spec

func WithBody

func WithBody(body any) Opt

WithBody adds a body for the operation

func WithDescription

func WithDescription(description string) Opt

WithDescription adss a description

func WithErrBadRequest

func WithErrBadRequest(message ...string) Opt

WithErrBadRequest creates a bad request error response Opt

func WithErrNotFound

func WithErrNotFound(message ...string) Opt

WithErrNotFound creates a not found error response Opt

func WithError

func WithError(errorCode int, message ...string) Opt

WithError creates an error response Opt

func WithForbidden

func WithForbidden(message ...string) Opt

WithForbidden creates a forbidden error response Opt

func WithInternalError

func WithInternalError(message ...string) Opt

WithInternalError creates an internal server error response Opt

func WithMethod

func WithMethod(m Method) Opt

WithMethod adds a method for the opration

func WithOriginalPath

func WithOriginalPath(p string) Opt

WithOriginalPath adds a path to the request

func WithParam

func WithParam(loc ParamLocation, title string, paramType ...string) Opt

WithParam appends a path parameter

func WithParams

func WithParams(params []*Parameter) Opt

WithParams merges params to operation

func WithPath

func WithPath(p string) Opt

WithPath adds a path to the request

func WithPathPrefix

func WithPathPrefix(p string) Opt

WithPathPrefix adds a prefix for the request

func WithResponse

func WithResponse(body any, code ...int) Opt

WithResponse appends a response

func WithSummary

func WithSummary(summary string) Opt

WithSummary adds a summary

func WithTags

func WithTags(tags ...string) Opt

WithTags appends tags to the operation

func WithUnauthorized

func WithUnauthorized(message ...string) Opt

WithUnauthorized creates an unauthorized error response Opt

type ParamLocation

type ParamLocation string

ParamLocation is a type for parameter location (header, path, query)

const (
	ParamLocationHeader ParamLocation = "header"
	ParamLocationPath   ParamLocation = "path"
	ParamLocationQuery  ParamLocation = "query"
)

Possible values for ParamLocation

type Parameter

type Parameter struct {
	Title    string
	Type     string
	Location ParamLocation
}

Parameter definition

type ReflectorOptions

type ReflectorOptions struct {
	OASVersion string
	Servers    []string
	Port       int

	Title       string
	Description string
	Version     string

	OpenAPIAuthorizationURL string
	APIKeyAuth              bool
}

ReflectorOptions for initing openapi3.Reflector

type Response

type Response struct {
	Code int
	Body any
}

Response defines a single response data (code + entity)

type Spec

type Spec struct {
	Path         string
	OriginalPath string
	PathPrefix   string
	Method       Method
	Body         interface{}
	Responses    []*Response
	Parameters   []*Parameter
	Tags         []string
	Summary      string
	Description  string
	Op           *openapi3.Operation
	Auth         bool
	AuthAPI      bool
}

Spec holds data for creating an OpenAPI spec for a route

func Delete

func Delete(routePath string, res any, opts ...Opt) *Spec

Delete constructs a GET operation

func Get

func Get(routePath string, res any, opts ...Opt) *Spec

Get constructs a GET operation

func Of

func Of(opts ...Opt) *Spec

Of constructs a new Spec

func Patch

func Patch(routePath string, body any, res any, opts ...Opt) *Spec

Patch constructs a PATCH operation

func Post

func Post(routePath string, body any, res any, opts ...Opt) *Spec

Post constructs a POST operation

func Put

func Put(routePath string, body any, res any, opts ...Opt) *Spec

Put constructs a PUT operation

func (*Spec) Build

func (s *Spec) Build(ref *openapi3.Reflector) error

Build builds an openapi3.Spec

func (*Spec) FullPath

func (s *Spec) FullPath() string

FullPath returns url with prefix if present

func (*Spec) FullRouterPath

func (s *Spec) FullRouterPath() string

FullRouterPath returns url with prefix if present

func (*Spec) With

func (s *Spec) With(opts ...Opt) *Spec

With is a generic method to add/replace opts after Spec is already created

func (*Spec) WithAPIAuth

func (s *Spec) WithAPIAuth() *Spec

WithAPIAuth set api auth for spec

func (*Spec) WithAuth

func (s *Spec) WithAuth() *Spec

WithAuth set auth for spec

func (*Spec) WithQueryObject

func (s *Spec) WithQueryObject(obj any) *Spec

WithQueryObject ...

func (*Spec) WithTags

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

WithTags ...