spec

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Apr 8, 2023 License: BSD-3-Clause Imports: 22 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrUnknownTypeForReference indicates that a resolved reference was found in an unsupported container type
	ErrUnknownTypeForReference = errors.New("unknown type for the resolved reference")

	// ErrResolveRefNeedsAPointer indicates that a $ref target must be a valid JSON pointer
	ErrResolveRefNeedsAPointer = errors.New("resolve ref: target needs to be a pointer")

	// ErrDerefUnsupportedType indicates that a resolved reference was found in an unsupported container type.
	// At the moment, $ref are supported only inside: schemas, parameters, responses, path items
	ErrDerefUnsupportedType = errors.New("deref: unsupported type")

	// ErrComposeUnsupportedType indicates that $ref expansion is attempted on some invalid type
	ErrComposeUnsupportedType = errors.New("compose: unsupported type. Input should be of type *Parameter or *Response")
)

Error codes

View Source 
var PathLoader = func(pth string) (json.RawMessage, error) {
	data, err := swag.LoadFromFileOrHTTP(pth)
	if err != nil {
		return nil, err
	}
	return json.RawMessage(data), nil
}

PathLoader is a function to use when loading remote refs.

This is a package level default. It may be overridden or bypassed by specifying the loader in ComposeOptions.

NOTE: if you are using the go-openapi/loads package, it will override this value with its own default (a loader to retrieve YAML documents as well as JSON ones).

Functions

func Asset 

func Asset(name string) ([]byte, error)

Asset loads and returns the asset for the given name. It returns an error if the asset could not be found or could not be loaded.

func ComposeSpec 

func ComposeSpec(spec *Swagger, options *specs.ExpandOptions) error

ComposeSpec composes the references in a swagger spec

func ResolveItems deprecated 

func ResolveItems(root interface{}, ref specs.Ref, options *specs.ExpandOptions) (*specs.Items, error)

ResolveItems resolves parameter items reference against a context root and base path.

Deprecated: use ResolveItemsWithBase instead

func ResolveItemsWithBase 

func ResolveItemsWithBase(root interface{}, ref specs.Ref, options *specs.ExpandOptions) (*specs.Items, error)

ResolveItemsWithBase resolves parameter items reference against a context root and base path.

NOTE: stricly speaking, this construct is not supported by Swagger 2.0. Similarly, $ref are forbidden in response headers.

func ResolveParameter 

func ResolveParameter(root interface{}, ref specs.Ref) (*specs.Parameter, error)

ResolveParameter resolves a parameter reference against a context root

func ResolveParameterWithBase 

func ResolveParameterWithBase(root interface{}, ref specs.Ref, options *specs.ExpandOptions) (*specs.Parameter, error)

ResolveParameterWithBase resolves a parameter reference against a context root and base path

func ResolveRef 

func ResolveRef(root interface{}, ref *specs.Ref) (*specs.Schema, error)

ResolveRef resolves a reference for a schema against a context root ref is guaranteed to be in root (no need to go to external files)

ResolveRef is ONLY called from the code generation module

func ResolveRefWithBase 

func ResolveRefWithBase(root interface{}, ref *specs.Ref, options *specs.ExpandOptions) (*specs.Schema, error)

ResolveRefWithBase resolves a reference against a context root with preservation of base path

Types

type Content 

type Content struct {
	specs.Refable
	ContentProps
	specs.VendorExtensible
}

func NewContent 

func NewContent() *Content

func (Content) JSONLookup 

func (c Content) JSONLookup(token string) (interface{}, error)

JSONLookup look up a value by the json property name

func (Content) MarshalJSON 

func (c Content) MarshalJSON() ([]byte, error)

MarshalJSON converts this items object to JSON

func (*Content) UnmarshalJSON 

func (c *Content) UnmarshalJSON(data []byte) error

UnmarshalJSON hydrates this items instance with the data from JSON

type ContentProps 

type ContentProps struct {
	Description string                  `json:"description,omitempty"`
	Schema      *specs.Schema           `json:"schema,omitempty"`
	Headers     map[string]specs.Header `json:"headers,omitempty"`
	Examples    map[string]interface{}  `json:"examples,omitempty"`
}

type Operation 

type Operation struct {
	specs.VendorExtensible
	OperationProps
}

Operation describes a single API operation on a path.

For more information: http://goo.gl/8us55a#operationObject

func NewOperation 

func NewOperation(id string) *Operation

NewOperation creates a new operation instance. It expects an ID as parameter but not passing an ID is also valid.

func (*Operation) AddParam 

func (o *Operation) AddParam(param *specs.Parameter) *Operation

AddParam adds a parameter to this operation, when a parameter for that location and with that name already exists it will be replaced

func (*Operation) Deprecate 

func (o *Operation) Deprecate() *Operation

Deprecate marks the operation as deprecated

func (*Operation) GobDecode 

func (o *Operation) GobDecode(b []byte) error

GobDecode provides a safe gob decoder for Operation, including empty security requirements

func (Operation) GobEncode 

func (o Operation) GobEncode() ([]byte, error)

GobEncode provides a safe gob encoder for Operation, including empty security requirements

func (Operation) JSONLookup 

func (o Operation) JSONLookup(token string) (interface{}, error)

JSONLookup look up a value by the json property name

func (Operation) MarshalJSON 

func (o Operation) MarshalJSON() ([]byte, error)

MarshalJSON converts this items object to JSON

func (*Operation) RemoveParam 

func (o *Operation) RemoveParam(name, in string) *Operation

RemoveParam removes a parameter from the operation

func (*Operation) RespondsWith 

func (o *Operation) RespondsWith(code int, response *Response) *Operation

RespondsWith adds a status code response to the operation. When the code is 0 the value of the response will be used as default response value. When the value of the response is nil it will be removed from the operation

func (*Operation) SecuredWith 

func (o *Operation) SecuredWith(name string, scopes ...string) *Operation

SecuredWith adds a security scope to this operation.

func (*Operation) SuccessResponse 

func (o *Operation) SuccessResponse() (*Response, int, bool)

SuccessResponse gets a success response model

func (*Operation) Undeprecate 

func (o *Operation) Undeprecate() *Operation

Undeprecate marks the operation as not deprected

func (*Operation) UnmarshalJSON 

func (o *Operation) UnmarshalJSON(data []byte) error

UnmarshalJSON hydrates this items instance with the data from JSON

func (*Operation) WithConsumes 

func (o *Operation) WithConsumes(mediaTypes ...string) *Operation

WithConsumes adds media types for incoming body values

func (*Operation) WithDefaultResponse 

func (o *Operation) WithDefaultResponse(response *Response) *Operation

WithDefaultResponse adds a default response to the operation. Passing a nil value will remove the response

func (*Operation) WithDescription 

func (o *Operation) WithDescription(description string) *Operation

WithDescription sets the description on this operation, allows for chaining

func (*Operation) WithExternalDocs 

func (o *Operation) WithExternalDocs(description, url string) *Operation

WithExternalDocs sets/removes the external docs for/from this operation. When you pass empty strings as params the external documents will be removed. When you pass non-empty string as one value then those values will be used on the external docs object. So when you pass a non-empty description, you should also pass the url and vice versa.

func (*Operation) WithID 

func (o *Operation) WithID(id string) *Operation

WithID sets the ID property on this operation, allows for chaining.

func (*Operation) WithProduces 

func (o *Operation) WithProduces(mediaTypes ...string) *Operation

WithProduces adds media types for outgoing body values

func (*Operation) WithSummary 

func (o *Operation) WithSummary(summary string) *Operation

WithSummary sets the summary on this operation, allows for chaining

func (*Operation) WithTags 

func (o *Operation) WithTags(tags ...string) *Operation

WithTags adds tags for this operation

type OperationProps 

type OperationProps struct {
	Description  string                       `json:"description,omitempty"`
	Consumes     []string                     `json:"consumes,omitempty"`
	Produces     []string                     `json:"produces,omitempty"`
	Schemes      []string                     `json:"schemes,omitempty"`
	Tags         []string                     `json:"tags,omitempty"`
	Summary      string                       `json:"summary,omitempty"`
	ExternalDocs *specs.ExternalDocumentation `json:"externalDocs,omitempty"`
	ID           string                       `json:"operationId,omitempty"`
	Deprecated   bool                         `json:"deprecated,omitempty"`
	Security     []map[string][]string        `json:"security,omitempty"`
	Parameters   []specs.Parameter            `json:"parameters,omitempty"`
	Responses    *Responses                   `json:"responses,omitempty"`
	RequestBody  *RequestBody                 `json:"requestBody,omitempty"`
}

OperationProps describes an operation

NOTES: - schemes, when present must be from [http, https, ws, wss]: see validate - Security is handled as a special case: see MarshalJSON function

func (*OperationProps) GobDecode 

func (op *OperationProps) GobDecode(b []byte) error

GobDecode provides a safe gob decoder for Operation, including empty security requirements

func (OperationProps) GobEncode 

func (op OperationProps) GobEncode() ([]byte, error)

GobEncode provides a safe gob encoder for Operation, including empty security requirements

func (OperationProps) MarshalJSON 

func (op OperationProps) MarshalJSON() ([]byte, error)

MarshalJSON takes care of serializing operation properties to JSON

We use a custom marhaller here to handle a special cases related to the Security field. We need to preserve zero length slice while omitting the field when the value is nil/unset.

type PathItem 

type PathItem struct {
	specs.Refable
	specs.VendorExtensible
	PathItemProps
}

PathItem describes the operations available on a single path. A Path Item may be empty, due to [ACL constraints](http://goo.gl/8us55a#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.

For more information: http://goo.gl/8us55a#pathItemObject

func ResolvePathItem deprecated 

func ResolvePathItem(root interface{}, ref specs.Ref, options *specs.ExpandOptions) (*PathItem, error)

ResolvePathItem resolves response a path item against a context root and base path

Deprecated: use ResolvePathItemWithBase instead

func ResolvePathItemWithBase 

func ResolvePathItemWithBase(root interface{}, ref specs.Ref, options *specs.ExpandOptions) (*PathItem, error)

ResolvePathItemWithBase resolves response a path item against a context root and base path

func (PathItem) JSONLookup 

func (p PathItem) JSONLookup(token string) (interface{}, error)

JSONLookup look up a value by the json property name

func (PathItem) MarshalJSON 

func (p PathItem) MarshalJSON() ([]byte, error)

MarshalJSON converts this items object to JSON

func (*PathItem) UnmarshalJSON 

func (p *PathItem) UnmarshalJSON(data []byte) error

UnmarshalJSON hydrates this items instance with the data from JSON

type PathItemProps 

type PathItemProps struct {
	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 []specs.Parameter `json:"parameters,omitempty"`
}

PathItemProps the path item specific properties

type Paths 

type Paths struct {
	specs.VendorExtensible
	Paths map[string]PathItem `json:"-"` // custom serializer to flatten this, each entry must start with "/"
}

Paths holds the relative paths to the individual endpoints. The path is appended to the [`basePath`](http://goo.gl/8us55a#swaggerBasePath) in order to construct the full URL. The Paths may be empty, due to [ACL constraints](http://goo.gl/8us55a#securityFiltering).

For more information: http://goo.gl/8us55a#pathsObject

func (Paths) JSONLookup 

func (p Paths) JSONLookup(token string) (interface{}, error)

JSONLookup look up a value by the json property name

func (Paths) MarshalJSON 

func (p Paths) MarshalJSON() ([]byte, error)

MarshalJSON converts this items object to JSON

func (*Paths) UnmarshalJSON 

func (p *Paths) UnmarshalJSON(data []byte) error

UnmarshalJSON hydrates this items instance with the data from JSON

type RequestBody added in v0.1.1 

type RequestBody struct {
	specs.Schema
	specs.Refable
	specs.VendorExtensible
	RequestBodyProps
}

func (RequestBody) JSONLookup added in v0.1.1 

func (rb RequestBody) JSONLookup(token string) (any, error)

JSONLookup implements an interface to customize json pointer lookup

func (RequestBody) MarshalJSON added in v0.1.1 

func (rb RequestBody) MarshalJSON() ([]byte, error)

MarshalJSON converts this items object to JSON

func (*RequestBody) UnmarshalJSON added in v0.1.1 

func (rb *RequestBody) UnmarshalJSON(data []byte) error

UnmarshalJSON hydrates this items instance with the data from JSON

type RequestBodyProps added in v0.1.1 

type RequestBodyProps struct {
	Description string             `json:"description,omitempty"`
	Content     map[string]Content `json:"content,omitempty"`
	Required    bool               `json:"required"`
}

type Response 

type Response struct {
	specs.Refable
	ResponseProps
	specs.VendorExtensible
}

Response describes a single response from an API Operation. interface{} For more information: http://goo.gl/8us55a#responseObject

func NewResponse 

func NewResponse() *Response

NewResponse creates a new response instance

func ResolveResponse 

func ResolveResponse(root interface{}, ref specs.Ref) (*Response, error)

ResolveResponse resolves response a reference against a context root

func ResolveResponseWithBase 

func ResolveResponseWithBase(root interface{}, ref specs.Ref, options *specs.ExpandOptions) (*Response, error)

ResolveResponseWithBase resolves response a reference against a context root and base path

func (*Response) AddExample 

func (r *Response) AddExample(mediaType string, example interface{}) *Response

AddExample adds an example to this response

func (*Response) AddHeader 

func (r *Response) AddHeader(name string, header *specs.Header) *Response

AddHeader adds a header to this response

func (Response) JSONLookup 

func (r Response) JSONLookup(token string) (interface{}, error)

JSONLookup look up a value by the json property name

func (Response) MarshalJSON 

func (r Response) MarshalJSON() ([]byte, error)

MarshalJSON converts this items object to JSON

func (*Response) RemoveHeader 

func (r *Response) RemoveHeader(name string) *Response

RemoveHeader removes a header from this response

func (*Response) UnmarshalJSON 

func (r *Response) UnmarshalJSON(data []byte) error

UnmarshalJSON hydrates this items instance with the data from JSON

func (*Response) WithDescription 

func (r *Response) WithDescription(description string) *Response

WithDescription sets the description on this response, allows for chaining

func (*Response) WithSchema 

func (r *Response) WithSchema(schema *specs.Schema) *Response

WithSchema sets the schema on this response, allows for chaining. Passing a nil argument removes the schema from this response

type ResponseProps 

type ResponseProps struct {
	Description string                  `json:"description"`
	Schema      *specs.Schema           `json:"schema,omitempty"`
	Headers     map[string]specs.Header `json:"headers,omitempty"`
	Examples    map[string]interface{}  `json:"examples,omitempty"`
	Content     map[string]Content      `json:"content,omitempty"`
}

ResponseProps properties specific to a response

type Responses 

type Responses struct {
	specs.VendorExtensible
	ResponsesProps
}

Responses is a container for the expected responses of an operation. The container maps a HTTP response code to the expected response. It is not expected from the documentation to necessarily cover all possible HTTP response codes, since they may not be known in advance. However, it is expected from the documentation to cover a successful operation response and any known errors.

The `default` can be used a default response object for all HTTP codes that are not covered individually by the specification.

The `Responses Object` MUST contain at least one response code, and it SHOULD be the response for a successful operation call.

For more information: http://goo.gl/8us55a#responsesObject

func (Responses) JSONLookup 

func (r Responses) JSONLookup(token string) (interface{}, error)

JSONLookup implements an interface to customize json pointer lookup

func (Responses) MarshalJSON 

func (r Responses) MarshalJSON() ([]byte, error)

MarshalJSON converts this items object to JSON

func (*Responses) UnmarshalJSON 

func (r *Responses) UnmarshalJSON(data []byte) error

UnmarshalJSON hydrates this items instance with the data from JSON

type ResponsesProps 

type ResponsesProps struct {
	Default             *Response
	StatusCodeResponses map[int]Response
}

ResponsesProps describes all responses for an operation. It tells what is the default response and maps all responses with a HTTP status code.

func (ResponsesProps) MarshalJSON 

func (r ResponsesProps) MarshalJSON() ([]byte, error)

MarshalJSON marshals responses as JSON

func (*ResponsesProps) UnmarshalJSON 

func (r *ResponsesProps) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals responses from JSON

type Server 

type Server struct {
	URL         string           `json:"url,omitempty"`
	Description string           `json:"description,omitempty"`
	Variables   []ServerVariable `json:"variables,omitempty"`
}

type ServerVariable 

type ServerVariable struct {
	Default     string   `json:"default,omitempty"`
	Description string   `json:"description,omitempty"`
	Enum        []string `json:"enum,omitempty"`
}

type Swagger 

type Swagger struct {
	specs.VendorExtensible
	SwaggerProps
}

Swagger this is the root document object for the API specification. It combines what previously was the Resource Listing and API Declaration (version 1.2 and earlier) together into one document.

For more information: http://goo.gl/8us55a#swagger-object-

func (*Swagger) GobDecode 

func (s *Swagger) GobDecode(b []byte) error

GobDecode provides a safe gob decoder for Swagger, including extensions

func (Swagger) GobEncode 

func (s Swagger) GobEncode() ([]byte, error)

GobEncode provides a safe gob encoder for Swagger, including extensions

func (Swagger) JSONLookup 

func (s Swagger) JSONLookup(token string) (interface{}, error)

JSONLookup look up a value by the json property name

func (Swagger) MarshalJSON 

func (s Swagger) MarshalJSON() ([]byte, error)

MarshalJSON marshals this swagger structure to json

func (*Swagger) UnmarshalJSON 

func (s *Swagger) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals a swagger spec from json

type SwaggerProps 

type SwaggerProps struct {
	OpenApi             string                       `json:"openapi,omitempty"`
	ID                  string                       `json:"id,omitempty"`
	Consumes            []string                     `json:"consumes,omitempty"`
	Produces            []string                     `json:"produces,omitempty"`
	Schemes             []string                     `json:"schemes,omitempty"`
	Swagger             string                       `json:"swagger,omitempty"`
	Info                *specs.Info                  `json:"info,omitempty"`
	Host                string                       `json:"host,omitempty"`
	BasePath            string                       `json:"basePath,omitempty"`
	Paths               *Paths                       `json:"paths"`
	Definitions         specs.Definitions            `json:"definitions,omitempty"`
	Parameters          map[string]specs.Parameter   `json:"parameters,omitempty"`
	Responses           map[string]Response          `json:"responses,omitempty"`
	SecurityDefinitions specs.SecurityDefinitions    `json:"securityDefinitions,omitempty"`
	Security            []map[string][]string        `json:"security,omitempty"`
	Tags                []specs.Tag                  `json:"tags,omitempty"`
	ExternalDocs        *specs.ExternalDocumentation `json:"externalDocs,omitempty"`
	Servers             []Server                     `json:"servers,omitempty"`
	Components          specs.SchemaOrArray          `json:"components,omitempty"`
}

SwaggerProps captures the top-level properties of an Api specification

NOTE: validation rules - the scheme, when present must be from [http, https, ws, wss] - BasePath must start with a leading "/" - Paths is required

func (*SwaggerProps) GobDecode 

func (o *SwaggerProps) GobDecode(b []byte) error

GobDecode provides a safe gob decoder for SwaggerProps, including empty security requirements

func (SwaggerProps) GobEncode 

func (o SwaggerProps) GobEncode() ([]byte, error)

GobEncode provides a safe gob encoder for SwaggerProps, including empty security requirements

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.