swagger

Documentation

Index

• Variables
• func CheckSecurityRequirements(obj *Object, getScopes func(b *ucon.Bubble) ([]string, error)) ucon.MiddlewareFunc
• func RequestValidator() ucon.MiddlewareFunc
• type Contact
• type Definitions
• type Example
• type ExternalDocumentation
• type FieldInfo
  • func (fiInfo *FieldInfo) Anonymous() bool
  • func (fiInfo *FieldInfo) Ignored() bool
  • func (fiInfo *FieldInfo) Name() string
  • func (fiInfo *FieldInfo) Type() reflect.Type
• type HandlerInfo
  • func NewHandlerInfo(handler interface{}) *HandlerInfo
  • func (wr *HandlerInfo) Handler() interface{}
  • func (wr *HandlerInfo) Value(key interface{}) interface{}
• type Header
• type Headers
• type Info
• type Items
• type License
• type Object
• type Operation
• type Options
• type Parameter
• type ParametersDefinitions
• type PathItem
• type Paths
• type Plugin
  • func NewPlugin(opts *Options) *Plugin
  • func (p *Plugin) AddTag(tag *Tag) *Tag
  • func (p *Plugin) HandlersScannerProcess(m *ucon.ServeMux, rds []*ucon.RouteDefinition) error
• type Reference
• type Response
• type Responses
• type ResponsesDefinitions
• type Schema
  • func (schema *Schema) ShallowCopy() *Schema
• type Scopes
• type SecurityDefinitions
• type SecurityRequirement
• type SecurityScheme
• type Tag
• type TagSwagger
  • func NewTagSwagger(tag reflect.StructTag) TagSwagger
  • func (swaggerTag TagSwagger) Default() string
  • func (swaggerTag TagSwagger) Empty() bool
  • func (swaggerTag TagSwagger) Enum() []string
  • func (swaggerTag TagSwagger) In() string
  • func (swaggerTag TagSwagger) MaxLength() *int
  • func (swaggerTag TagSwagger) Maximum() *int
  • func (swaggerTag TagSwagger) MinLength() *int
  • func (swaggerTag TagSwagger) Minimum() *int
  • func (swaggerTag TagSwagger) Name() string
  • func (swaggerTag TagSwagger) Pattern() string
  • func (swaggerTag TagSwagger) Private() bool
  • func (swaggerTag TagSwagger) Required() bool
• type TypeSchema
  • func (ts *TypeSchema) SwaggerSchema() (*Schema, error)

Variables

var (
	// ErrSecurityDefinitionsIsRequired is returned when security definition is missing in object or path items.
	ErrSecurityDefinitionsIsRequired = newSecurityError(http.StatusInternalServerError, "swagger: SecurityDefinitions is required")
	// ErrSecuritySettingsAreWrong is returned when required scope is missing in object or path items.
	ErrSecuritySettingsAreWrong = newSecurityError(http.StatusInternalServerError, "swagger: security settings are wrong")
	// ErrNotImplemented is returned when specified type is not implemented.
	ErrNotImplemented = newSecurityError(http.StatusInternalServerError, "swagger: not implemented")
	// ErrAccessDenied is returned when access user doesn't have a access grant.
	ErrAccessDenied = newSecurityError(http.StatusUnauthorized, "swagger: access denied")
)

var DefaultTypeSchemaMapper = map[reflect.Type]*TypeSchema{
	reflect.TypeOf(time.Time{}): &TypeSchema{
		RefName: "",
		Schema: &Schema{
			Type:   "string",
			Format: "date-time",
		},
		AllowRef: false,
	},
}

DefaultTypeSchemaMapper is used for mapping from go-type to swagger-schema.

var DefaultValidator ucon.Validator

DefaultValidator used in RequestValidator.

Functions

func CheckSecurityRequirements

func CheckSecurityRequirements(obj *Object, getScopes func(b *ucon.Bubble) ([]string, error)) ucon.MiddlewareFunc

CheckSecurityRequirements about request.

func RequestValidator

func RequestValidator() ucon.MiddlewareFunc

RequestValidator checks request object validity by swagger tag.

Types

type Contact

type Contact struct {
	Name  string `json:"name,omitempty"`
	URL   string `json:"url,omitempty"`
	Email string `json:"email,omitempty"`
}

Contact is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#contact-object

type Definitions

type Definitions map[string]*Schema

Definitions is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#definitions-object

type Example

type Example map[string]interface{}

Example is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#example-object

type ExternalDocumentation

type ExternalDocumentation struct {
	Description string `json:"description,omitempty"`
	URL         string `json:"url" swagger:",req"`
}

ExternalDocumentation is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#externalDocumentationObject

type FieldInfo

type FieldInfo struct {
	Base reflect.StructField

	TypeSchema   *TypeSchema
	EmitAsString bool
	Enum         []interface{} // from tag, e.g. swagger:",enum=ok|ng"
}

FieldInfo has a information for struct field. It contains Type information and Tag information.

func (*FieldInfo) Anonymous

func (fiInfo *FieldInfo) Anonymous() bool

Anonymous is an embedded field.

func (*FieldInfo) Ignored

func (fiInfo *FieldInfo) Ignored() bool

Ignored is an ignored field.

func (*FieldInfo) Name

func (fiInfo *FieldInfo) Name() string

Name returns field name on swagger.

func (*FieldInfo) Type

func (fiInfo *FieldInfo) Type() reflect.Type

Type returns field type.

type HandlerInfo

type HandlerInfo struct {
	HandlerFunc interface{}
	Operation
	Context ucon.Context
}

HandlerInfo is a container of the handler function and the operation with the context. HandlerInfo implements interfaces of ucon.HandlerContainer and ucon.Context.

func NewHandlerInfo

func NewHandlerInfo(handler interface{}) *HandlerInfo

NewHandlerInfo returns new HandlerInfo containing given handler function.

func (*HandlerInfo) Handler

func (wr *HandlerInfo) Handler() interface{}

Handler returns contained handler function.

func (*HandlerInfo) Value

func (wr *HandlerInfo) Value(key interface{}) interface{}

Value returns the value contained with the key.

type Header

type Header struct {
	Description      string        `json:"description,omitempty"`
	Type             string        `json:"type" swagger:",req"`
	Format           string        `json:"format,omitempty"`
	Items            *Items        `json:"items,omitempty"`
	CollectionFormat string        `json:"collectionFormat,omitempty"`
	Default          interface{}   `json:"default,omitempty"`
	Maximum          *int          `json:"maximum,omitempty"`
	ExclusiveMaximum *bool         `json:"exclusiveMaximum,omitempty"`
	Minimum          *int          `json:"minimum,omitempty"`
	ExclusiveMinimum *bool         `json:"exclusiveMinimum,omitempty"`
	MaxLength        *int          `json:"maxLength,omitempty"`
	MinLength        *int          `json:"minLength,omitempty"`
	Pattern          string        `json:"pattern,omitempty"`
	MaxItems         *int          `json:"maxItems,omitempty"`
	MinItems         *int          `json:"minItems,omitempty"`
	UniqueItems      *bool         `json:"uniqueItems,omitempty"`
	Enum             []interface{} `json:"enum,omitempty"`
	MultipleOf       *int          `json:"multipleOf,omitempty"`
}

Header is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#header-object

type Headers

type Headers map[string]*Header

Headers is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#headers-object

type Info

type Info struct {
	Title          string   `json:"title" swagger:",req"`
	Description    string   `json:"description,omitempty"`
	TermsOfService string   `json:"termsOfService,omitempty"`
	Contact        *Contact `json:"contact,omitempty"`
	License        *License `json:"license,omitempty"`
	Version        string   `json:"version" swagger:",req"`
}

Info is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#infoObject

type Items

type Items struct {
	Type             string        `json:"type" swagger:",req"`
	Format           string        `json:"format,omitempty"`
	Items            *Items        `json:"items,omitempty"`
	CollectionFormat string        `json:"collectionFormat,omitempty"`
	Default          interface{}   `json:"default,omitempty"`
	Maximum          *int          `json:"maximum,omitempty"`
	ExclusiveMaximum *bool         `json:"exclusiveMaximum,omitempty"`
	Minimum          *int          `json:"minimum,omitempty"`
	ExclusiveMinimum *bool         `json:"exclusiveMinimum,omitempty"`
	MaxLength        *int          `json:"maxLength,omitempty"`
	MinLength        *int          `json:"minLength,omitempty"`
	Pattern          string        `json:"pattern,omitempty"`
	MaxItems         *int          `json:"maxItems,omitempty"`
	MinItems         *int          `json:"minItems,omitempty"`
	UniqueItems      *bool         `json:"uniqueItems,omitempty"`
	Enum             []interface{} `json:"enum,omitempty"`
	MultipleOf       *int          `json:"multipleOf,omitempty"`
}

Items is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#items-object

type License

type License struct {
	Name string `json:"name" swagger:",req"`
	URL  string `json:"url,omitempty"`
}

License is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#license-object

type Object

type Object struct {
	Swagger             string                 `json:"swagger" swagger:",req,d=2.0"`
	Info                *Info                  `json:"info" swagger:",req"`
	Host                string                 `json:"host,omitempty"`
	BasePath            string                 `json:"basePath,omitempty"`
	Schemes             []string               `json:"schemes,omitempty" swagger:",d=https"`
	Consumes            []string               `json:"consumes,omitempty" swagger:",d=application/json"`
	Produces            []string               `json:"produces,omitempty" swagger:",d=application/json"`
	Paths               Paths                  `json:"paths" swagger:",req"`
	Definitions         Definitions            `json:"definitions,omitempty"`
	Parameters          ParametersDefinitions  `json:"parameters,omitempty"`
	Responses           ResponsesDefinitions   `json:"responses,omitempty"`
	SecurityDefinitions SecurityDefinitions    `json:"securityDefinitions,omitempty"`
	Security            []SecurityRequirement  `json:"security,omitempty"`
	Tags                []*Tag                 `json:"tags,omitempty"`
	ExternalDocs        *ExternalDocumentation `json:"externalDocs,omitempty"`
}

Object is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swagger-object

type Operation

type Operation struct {
	Tags         []string               `json:"tags,omitempty"`
	Summary      string                 `json:"summary,omitempty"`
	Description  string                 `json:"description,omitempty"`
	ExternalDocs *ExternalDocumentation `json:"externalDocs,omitempty"`
	OperationID  string                 `json:"operationId,omitempty"`
	Consumes     []string               `json:"consumes,omitempty"`
	Produces     []string               `json:"produces,omitempty"`
	Parameters   []*Parameter           `json:"parameters,omitempty"`
	Responses    Responses              `json:"responses" swagger:",req"`
	Schemes      []string               `json:"schemes,omitempty"`
	Deprecated   bool                   `json:"deprecated,omitempty"`
	Security     []SecurityRequirement  `json:"security,omitempty"`
}

Operation is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object

type Options

type Options struct {
	Object                 *Object
	DefinitionNameModifier func(refT reflect.Type, defName string) string
}

Options is a container of optional settings to configure a plugin.

type Parameter

type Parameter struct {
	Name        string `json:"name" swagger:",req"`
	In          string `json:"in" swagger:",req,enum=query|header|path|formData|body"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required,omitempty"`

	// If in is "body":
	Schema *Schema `json:"schema,omitempty"`

	// If in is any value other than "body":
	Type             string        `json:"type,omitempty"`
	Format           string        `json:"format,omitempty"`
	AllowEmptyValue  bool          `json:"allowEmptyValue,omitempty"`
	Items            *Items        `json:"items,omitempty"`
	CollectionFormat string        `json:"collectionFormat,omitempty"`
	Default          interface{}   `json:"default,omitempty"`
	Maximum          *int          `json:"maximum,omitempty"`
	ExclusiveMaximum *bool         `json:"exclusiveMaximum,omitempty"`
	Minimum          *int          `json:"minimum,omitempty"`
	ExclusiveMinimum *bool         `json:"exclusiveMinimum,omitempty"`
	MaxLength        *int          `json:"maxLength,omitempty"`
	MinLength        *int          `json:"minLength,omitempty"`
	Pattern          string        `json:"pattern,omitempty"`
	MaxItems         *int          `json:"maxItems,omitempty"`
	MinItems         *int          `json:"minItems,omitempty"`
	UniqueItems      *bool         `json:"uniqueItems,omitempty"`
	Enum             []interface{} `json:"enum,omitempty"`
	MultipleOf       *int          `json:"multipleOf,omitempty"`
}

Parameter is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameterObject

type ParametersDefinitions

type ParametersDefinitions map[string]*Parameter

ParametersDefinitions is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameters-definitions-object

type PathItem

type PathItem struct {
	Ref        string       `json:"$ref,omitempty"`
	Get        *Operation   `json:"get,omitempty"`
	Put        *Operation   `json:"put,omitempty"`
	Post       *Operation   `json:"post,omitempty"`
	Delete     *Operation   `json:"delete,omitempty"`
	Options    *Operation   `json:"options,omitempty"`
	Head       *Operation   `json:"head,omitempty"`
	Patch      *Operation   `json:"patch,omitempty"`
	Parameters []*Parameter `json:"parameters,omitempty"`
}

PathItem is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#pathItemObject

type Paths

type Paths map[string]*PathItem

Paths is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#pathsObject

type Plugin

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

Plugin is a holder for all of plugin settings.

func NewPlugin

func NewPlugin(opts *Options) *Plugin

NewPlugin returns new swagger plugin configured with the options.

func (*Plugin) AddTag

func (p *Plugin) AddTag(tag *Tag) *Tag

AddTag adds the tag to top-level tags definition.

func (*Plugin) HandlersScannerProcess

func (p *Plugin) HandlersScannerProcess(m *ucon.ServeMux, rds []*ucon.RouteDefinition) error

HandlersScannerProcess executes scanning all registered handlers to serve swagger.json.

type Reference

type Reference struct {
	Ref string `json:"$ref,omitempty"`
}

Reference is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#reference-object

type Response

type Response struct {
	Description string  `json:"description" swagger:",req"`
	Schema      *Schema `json:"schema,omitempty"`
	Headers     Headers `json:"headers,omitempty"`
	Examples    Example `json:"examples,omitempty"`

	// https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#reference-object
	Ref string `json:"$ref,omitempty"`
}

Response is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responseObject

type Responses

type Responses map[string]*Response

Responses is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responsesObject

type ResponsesDefinitions

type ResponsesDefinitions map[string]*Response

ResponsesDefinitions is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responses-definitions-object

type Schema

type Schema struct {
	Ref                  string             `json:"$ref,omitempty"`
	Format               string             `json:"format,omitempty"`
	Title                string             `json:"title,omitempty"`
	Description          string             `json:"description,omitempty"`
	Default              interface{}        `json:"default,omitempty"`
	Maximum              *int               `json:"maximum,omitempty"`
	ExclusiveMaximum     *bool              `json:"exclusiveMaximum,omitempty"`
	Minimum              *int               `json:"minimum,omitempty"`
	ExclusiveMinimum     *bool              `json:"exclusiveMinimum,omitempty"`
	MaxLength            *int               `json:"maxLength,omitempty"`
	MinLength            *int               `json:"minLength,omitempty"`
	Pattern              string             `json:"pattern,omitempty"`
	MaxItems             *int               `json:"maxItems,omitempty"`
	MinItems             *int               `json:"minItems,omitempty"`
	UniqueItems          *bool              `json:"uniqueItems,omitempty"`
	MaxProperties        *int               `json:"maxProperties,omitempty"`
	MinProperties        *int               `json:"minProperties,omitempty"`
	Required             []string           `json:"required,omitempty"`
	Enum                 []interface{}      `json:"enum,omitempty"`
	Type                 string             `json:"type,omitempty"`
	Items                *Schema            `json:"items,omitempty"`
	AllOf                []*Schema          `json:"allOf,omitempty"`
	Properties           map[string]*Schema `json:"properties,omitempty"`
	AdditionalProperties map[string]*Schema `json:"additionalProperties,omitempty"`
	Discriminator        string             `json:"discriminator,omitempty"`
	ReadOnly             *bool              `json:"readOnly,omitempty"`
	// Xml XML
	ExternalDocs *ExternalDocumentation `json:"externalDocs,omitempty"`
	Example      interface{}            `json:"example,omitempty"`
}

Schema is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject

func (*Schema) ShallowCopy

func (schema *Schema) ShallowCopy() *Schema

ShallowCopy returns a clone of *Schema.

type Scopes

type Scopes map[string]string

Scopes is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#scopesObject

type SecurityDefinitions

type SecurityDefinitions map[string]*SecurityScheme

SecurityDefinitions is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#security-definitions-object

type SecurityRequirement

type SecurityRequirement map[string][]string

SecurityRequirement is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#security-requirement-object

type SecurityScheme

type SecurityScheme struct {
	Type             string `json:"type" swagger:",req,enum=basic|apiKey|oauth2"`
	Description      string `json:"description,omitempty"`
	Name             string `json:"name" swagger:",req"`
	In               string `json:"in,omitempty" swagger:",enum=query|header"`
	Flow             string `json:"flow" swagger:",req"`
	AuthorizationURL string `json:"authorizationUrl" swagger:",req"`
	TokenURL         string `json:"tokenUrl" swagger:",req"`
	Scopes           Scopes `json:"scopes" swagger:",req"`
}

SecurityScheme is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#security-scheme-object

type Tag

type Tag struct {
	Name         string                 `json:"name" swagger:",req"`
	Description  string                 `json:"description,omitempty"`
	ExternalDocs *ExternalDocumentation `json:"externalDocs,omitempty"`
}

Tag is https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#tag-object

type TagSwagger

type TagSwagger reflect.StructTag

TagSwagger is a struct tag for setting attributes of swagger.

func NewTagSwagger

func NewTagSwagger(tag reflect.StructTag) TagSwagger

NewTagSwagger casts the tag to TagSwagger.

func (TagSwagger) Default

func (swaggerTag TagSwagger) Default() string

Default returns the default value of the field.

func (TagSwagger) Empty

func (swaggerTag TagSwagger) Empty() bool

Empty returns whether the text of the tag is empty.

func (TagSwagger) Enum

func (swaggerTag TagSwagger) Enum() []string

Enum returns the values allowed in the field.

func (TagSwagger) In

func (swaggerTag TagSwagger) In() string

In returns the place where the field will be put as parameter.

func (TagSwagger) MaxLength

func (swaggerTag TagSwagger) MaxLength() *int

MaxLength returns maximum length value from swagger tag.

func (TagSwagger) Maximum

func (swaggerTag TagSwagger) Maximum() *int

Maximum returns max value from swagger tag.

func (TagSwagger) MinLength

func (swaggerTag TagSwagger) MinLength() *int

MinLength returns minimum length value from swagger tag.

func (TagSwagger) Minimum

func (swaggerTag TagSwagger) Minimum() *int

Minimum returns min value from swagger tag.

func (TagSwagger) Name

func (swaggerTag TagSwagger) Name() string

Name returns the name for swagger. If the name is not given by `swagger` tag, `json` tag will be used instead.

func (TagSwagger) Pattern

func (swaggerTag TagSwagger) Pattern() string

Pattern returns pattern value from swagger tag.

func (TagSwagger) Private

func (swaggerTag TagSwagger) Private() bool

Private returns whether the field is hidden from swagger.

func (TagSwagger) Required

func (swaggerTag TagSwagger) Required() bool

Required returns whether the field is required.

type TypeSchema

type TypeSchema struct {
	RefName  string
	Schema   *Schema
	AllowRef bool
}

TypeSchema is a container of swagger schema and its attributes. RefName must be given if AllowRef is true.

func (*TypeSchema) SwaggerSchema

func (ts *TypeSchema) SwaggerSchema() (*Schema, error)

SwaggerSchema returns schema that is can use is swagger.json.