github.com/goadesign/goa/design

design

import "github.com/goadesign/goa/design"

Overview

Package design defines types which describe the data types used by action controllers. These are the data structures of the request payloads and parameters as well as the response payloads. There are primitive types corresponding to the JSON primitive types (bool, string, integer and number), array types which represent a collection of another type and object types corresponding to JSON objects (i.e. a map indexed by strings where each value may be any of the data types). On top of these the package also defines “user types” and “media types”. Both these types are named objects with additional properties (a description and for media types the media type identifier, links and views).

Index

Package files

api.go definitions.go dup.go example.go random.go security.go types.go validation.go

Constants

const (
    Continue           = "Continue"
    SwitchingProtocols = "SwitchingProtocols"

    OK                   = "OK"
    Created              = "Created"
    Accepted             = "Accepted"
    NonAuthoritativeInfo = "NonAuthoritativeInfo"
    NoContent            = "NoContent"
    ResetContent         = "ResetContent"
    PartialContent       = "PartialContent"

    MultipleChoices   = "MultipleChoices"
    MovedPermanently  = "MovedPermanently"
    Found             = "Found"
    SeeOther          = "SeeOther"
    NotModified       = "NotModified"
    UseProxy          = "UseProxy"
    TemporaryRedirect = "TemporaryRedirect"

    BadRequest                   = "BadRequest"
    Unauthorized                 = "Unauthorized"
    PaymentRequired              = "PaymentRequired"
    Forbidden                    = "Forbidden"
    NotFound                     = "NotFound"
    MethodNotAllowed             = "MethodNotAllowed"
    NotAcceptable                = "NotAcceptable"
    ProxyAuthRequired            = "ProxyAuthRequired"
    RequestTimeout               = "RequestTimeout"
    Conflict                     = "Conflict"
    Gone                         = "Gone"
    LengthRequired               = "LengthRequired"
    PreconditionFailed           = "PreconditionFailed"
    RequestEntityTooLarge        = "RequestEntityTooLarge"
    RequestURITooLong            = "RequestURITooLong"
    UnsupportedMediaType         = "UnsupportedMediaType"
    RequestedRangeNotSatisfiable = "RequestedRangeNotSatisfiable"
    ExpectationFailed            = "ExpectationFailed"
    Teapot                       = "Teapot"
    UnprocessableEntity          = "UnprocessableEntity"

    InternalServerError     = "InternalServerError"
    NotImplemented          = "NotImplemented"
    BadGateway              = "BadGateway"
    ServiceUnavailable      = "ServiceUnavailable"
    GatewayTimeout          = "GatewayTimeout"
    HTTPVersionNotSupported = "HTTPVersionNotSupported"
)

List of all built-in response names.

const (
    // Boolean is the type for a JSON boolean.
    Boolean = Primitive(BooleanKind)

    // Integer is the type for a JSON number without a fraction or exponent part.
    Integer = Primitive(IntegerKind)

    // Number is the type for any JSON number, including integers.
    Number = Primitive(NumberKind)

    // String is the type for a JSON string.
    String = Primitive(StringKind)

    // DateTime is the type for a JSON string parsed as a Go time.Time
    // DateTime expects an RFC3339 formatted value.
    DateTime = Primitive(DateTimeKind)

    // UUID is the type for a JSON string parsed as a Go uuid.UUID
    // UUID expects an RFC4122 formatted value.
    UUID = Primitive(UUIDKind)

    // Any is the type for an arbitrary JSON value (interface{} in Go).
    Any = Primitive(AnyKind)

    // File is the type for a file. This type can only be used in a multipart definition.
    File = Primitive(FileKind)
)

const DefaultView = "default"

DefaultView is the name of the default view.

Variables

var (
    // Design being built by DSL.
    Design *APIDefinition

    // GeneratedMediaTypes contains DSL definitions that were created by the design DSL and
    // need to be executed as a second pass.
    // An example of this are media types defined with CollectionOf: the element media type
    // must be defined first then the definition created by CollectionOf must execute.
    GeneratedMediaTypes MediaTypeRoot

    // ProjectedMediaTypes is a cache used by the MediaType strut Project method.
    ProjectedMediaTypes MediaTypeRoot

    // WildcardRegex is the regular expression used to capture path parameters.
    WildcardRegex = regexp.MustCompile(`/(?::|\*)([a-zA-Z0-9_]+)`)

    // DefaultDecoders contains the decoding definitions used when no Consumes DSL is found.
    DefaultDecoders []*EncodingDefinition

    // DefaultEncoders contains the encoding definitions used when no Produces DSL is found.
    DefaultEncoders []*EncodingDefinition

    // KnownEncoders contains the list of encoding packages and factories known by goa indexed
    // by MIME type.
    KnownEncoders = map[string]string{
        "application/json":      "github.com/goadesign/goa",
        "application/xml":       "github.com/goadesign/goa",
        "application/gob":       "github.com/goadesign/goa",
        "application/x-gob":     "github.com/goadesign/goa",
        "application/binc":      "github.com/goadesign/goa/encoding/binc",
        "application/x-binc":    "github.com/goadesign/goa/encoding/binc",
        "application/cbor":      "github.com/goadesign/goa/encoding/cbor",
        "application/x-cbor":    "github.com/goadesign/goa/encoding/cbor",
        "application/msgpack":   "github.com/goadesign/goa/encoding/msgpack",
        "application/x-msgpack": "github.com/goadesign/goa/encoding/msgpack",
    }

    // KnownEncoderFunctions contains the list of encoding encoder and decoder functions known
    // by goa indexed by MIME type.
    KnownEncoderFunctions = map[string][2]string{
        "application/json":      {"NewJSONEncoder", "NewJSONDecoder"},
        "application/xml":       {"NewXMLEncoder", "NewXMLDecoder"},
        "application/gob":       {"NewGobEncoder", "NewGobDecoder"},
        "application/x-gob":     {"NewGobEncoder", "NewGobDecoder"},
        "application/binc":      {"NewEncoder", "NewDecoder"},
        "application/x-binc":    {"NewEncoder", "NewDecoder"},
        "application/cbor":      {"NewEncoder", "NewDecoder"},
        "application/x-cbor":    {"NewEncoder", "NewDecoder"},
        "application/msgpack":   {"NewEncoder", "NewDecoder"},
        "application/x-msgpack": {"NewEncoder", "NewDecoder"},
    }

    // JSONContentTypes list the Content-Type header values that cause goa to encode or decode
    // JSON by default.
    JSONContentTypes = []string{"application/json"}

    // XMLContentTypes list the Content-Type header values that cause goa to encode or decode
    // XML by default.
    XMLContentTypes = []string{"application/xml"}

    // GobContentTypes list the Content-Type header values that cause goa to encode or decode
    // Gob by default.
    GobContentTypes = []string{"application/gob", "application/x-gob"}

    // ErrorMediaIdentifier is the media type identifier used for error responses.
    ErrorMediaIdentifier = "application/vnd.goa.error"

    // ErrorMedia is the built-in media type for error responses.
    ErrorMedia = &MediaTypeDefinition{
        UserTypeDefinition: &UserTypeDefinition{
            AttributeDefinition: &AttributeDefinition{
                Type:        errorMediaType,
                Description: "Error response media type",
                Example: map[string]interface{}{
                    "id":     "3F1FKVRR",
                    "status": "400",
                    "code":   "invalid_value",
                    "detail": "Value of ID must be an integer",
                    "meta":   map[string]interface{}{"timestamp": 1458609066},
                },
            },
            TypeName: "error",
        },
        Identifier: ErrorMediaIdentifier,
        Views:      map[string]*ViewDefinition{"default": errorMediaView},
    }
)

func CanonicalIdentifier

func CanonicalIdentifier(identifier string) string

CanonicalIdentifier returns the media type identifier sans suffix which is what the DSL uses to store and lookup media types.

func ExtractWildcards

func ExtractWildcards(path string) []string

ExtractWildcards returns the names of the wildcards that appear in path.

func HasFile

func HasFile(dt DataType) bool

HasFile returns true if the underlying type has any file attributes.

func HasKnownEncoder

func HasKnownEncoder(mimeType string) bool

HasKnownEncoder returns true if the encoder for the given MIME type is known by goa. MIME types with unknown encoders must be associated with a package path explicitly in the DSL.

func UserTypes

func UserTypes(dt DataType) map[string]*UserTypeDefinition

UserTypes traverses the data type recursively and collects all the user types used to define it. The returned map is indexed by type name.

type APIDefinition

type APIDefinition struct {
    // Name of API
    Name string
    // Title of API
    Title string
    // Description of API
    Description string
    // Version is the version of the API described by this design.
    Version string
    // Host is the default API hostname
    Host string
    // Schemes is the supported API URL schemes
    Schemes []string
    // BasePath is the common base path to all API endpoints
    BasePath string
    // Params define the common path parameters to all API endpoints
    Params *AttributeDefinition
    // Consumes lists the mime types supported by the API controllers
    Consumes []*EncodingDefinition
    // Produces lists the mime types generated by the API controllers
    Produces []*EncodingDefinition
    // Origins defines the CORS policies that apply to this API.
    Origins map[string]*CORSDefinition
    // TermsOfService describes or links to the API terms of service
    TermsOfService string
    // Contact provides the API users with contact information
    Contact *ContactDefinition
    // License describes the API license
    License *LicenseDefinition
    // Docs points to the API external documentation
    Docs *DocsDefinition
    // Resources is the set of exposed resources indexed by name
    Resources map[string]*ResourceDefinition
    // Types indexes the user defined types by name
    Types map[string]*UserTypeDefinition
    // MediaTypes indexes the API media types by canonical identifier
    MediaTypes map[string]*MediaTypeDefinition
    // Traits available to all API resources and actions indexed by name
    Traits map[string]*dslengine.TraitDefinition
    // Responses available to all API actions indexed by name
    Responses map[string]*ResponseDefinition
    // Response template factories available to all API actions indexed by name
    ResponseTemplates map[string]*ResponseTemplateDefinition
    // Built-in responses
    DefaultResponses map[string]*ResponseDefinition
    // Built-in response templates
    DefaultResponseTemplates map[string]*ResponseTemplateDefinition
    // DSLFunc contains the DSL used to create this definition if any
    DSLFunc func()
    // Metadata is a list of key/value pairs
    Metadata dslengine.MetadataDefinition
    // SecuritySchemes lists the available security schemes available
    // to the API.
    SecuritySchemes []*SecuritySchemeDefinition
    // Security defines security requirements for all the
    // resources and actions, unless overridden by Resource or
    // Action-level Security() calls.
    Security *SecurityDefinition
    // NoExamples indicates whether to bypass automatic example generation.
    NoExamples bool
    // contains filtered or unexported fields
}

APIDefinition defines the global properties of the API.

func NewAPIDefinition

func NewAPIDefinition() *APIDefinition

NewAPIDefinition returns a new design with built-in response templates.

func (*APIDefinition) Context

func (a *APIDefinition) Context() string

Context returns the generic definition name used in error messages.

func (*APIDefinition) DSL

func (a *APIDefinition) DSL() func()

DSL returns the initialization DSL.

func (*APIDefinition) DSLName

func (a *APIDefinition) DSLName() string

DSLName is the name of the DSL as displayed to the user during execution.

func (*APIDefinition) DependsOn

func (a *APIDefinition) DependsOn() []dslengine.Root

DependsOn returns the other roots this root depends on, nothing for APIDefinition.

func (*APIDefinition) Finalize

func (a *APIDefinition) Finalize()

Finalize sets the Consumes and Produces fields to the defaults if empty. Also it records built-in media types that are used by the user design.

func (*APIDefinition) IterateMediaTypes

func (a *APIDefinition) IterateMediaTypes(it MediaTypeIterator) error

IterateMediaTypes calls the given iterator passing in each media type sorted in alphabetical order. Iteration stops if an iterator returns an error and in this case IterateMediaTypes returns that error.

func (*APIDefinition) IterateResources

func (a *APIDefinition) IterateResources(it ResourceIterator) error

IterateResources calls the given iterator passing in each resource sorted in alphabetical order. Iteration stops if an iterator returns an error and in this case IterateResources returns that error.

func (*APIDefinition) IterateResponses

func (a *APIDefinition) IterateResponses(it ResponseIterator) error

IterateResponses calls the given iterator passing in each response sorted in alphabetical order. Iteration stops if an iterator returns an error and in this case IterateResponses returns that error.

func (*APIDefinition) IterateSets

func (a *APIDefinition) IterateSets(iterator dslengine.SetIterator)

IterateSets calls the given iterator possing in the API definition, user types, media types and finally resources.

func (*APIDefinition) IterateUserTypes

func (a *APIDefinition) IterateUserTypes(it UserTypeIterator) error

IterateUserTypes calls the given iterator passing in each user type sorted in alphabetical order. Iteration stops if an iterator returns an error and in this case IterateUserTypes returns that error.

func (*APIDefinition) MediaTypeWithIdentifier

func (a *APIDefinition) MediaTypeWithIdentifier(id string) *MediaTypeDefinition

MediaTypeWithIdentifier returns the media type with a matching media type identifier. Two media type identifiers match if their values sans suffix match. So for example “application/vnd.foo+xml”, “application/vnd.foo+json” and “application/vnd.foo” all match.

func (*APIDefinition) PathParams

func (a *APIDefinition) PathParams() *AttributeDefinition

PathParams returns the base path parameters of a.

func (*APIDefinition) RandomGenerator

func (a *APIDefinition) RandomGenerator() *RandomGenerator

RandomGenerator is seeded after the API name. It’s used to generate examples.

func (*APIDefinition) Reset

func (a *APIDefinition) Reset()

Reset sets all the API definition fields to their zero value except the default responses and default response templates.

func (*APIDefinition) Validate

func (a *APIDefinition) Validate() error

Validate tests whether the API definition is consistent: all resource parent names resolve to an actual resource.

type ActionDefinition

type ActionDefinition struct {
    // Action name, e.g. "create"
    Name string
    // Action description, e.g. "Creates a task"
    Description string
    // Docs points to the API external documentation
    Docs *DocsDefinition
    // Parent resource
    Parent *ResourceDefinition
    // Specific action URL schemes
    Schemes []string
    // Action routes
    Routes []*RouteDefinition
    // Map of possible response definitions indexed by name
    Responses map[string]*ResponseDefinition
    // Path and query string parameters
    Params *AttributeDefinition
    // Query string parameters only
    QueryParams *AttributeDefinition
    // Payload blueprint (request body) if any
    Payload *UserTypeDefinition
    // PayloadOptional is true if the request payload is optional, false otherwise.
    PayloadOptional bool
    // PayloadOptional is true if the request payload is multipart, false otherwise.
    PayloadMultipart bool
    // Request headers that need to be made available to action
    Headers *AttributeDefinition
    // Metadata is a list of key/value pairs
    Metadata dslengine.MetadataDefinition
    // Security defines security requirements for the action
    Security *SecurityDefinition
}

ActionDefinition defines a resource action. It defines both an HTTP endpoint and the shape of HTTP requests and responses made to that endpoint. The shape of requests is defined via “parameters”, there are path parameters parameters and a payload parameter (request body). (i.e. portions of the URL that define parameter values), query string

func (*ActionDefinition) AllParams

func (a *ActionDefinition) AllParams() *AttributeDefinition

AllParams returns the path and query string parameters of the action across all its routes.

func (*ActionDefinition) CanonicalScheme

func (a *ActionDefinition) CanonicalScheme() string

CanonicalScheme returns the preferred scheme for making requests. Favor secure schemes.

func (*ActionDefinition) Context

func (a *ActionDefinition) Context() string

Context returns the generic definition name used in error messages.

func (*ActionDefinition) EffectiveSchemes

func (a *ActionDefinition) EffectiveSchemes() []string

EffectiveSchemes return the URL schemes that apply to the action. Looks recursively into action resource, parent resources and API.

func (*ActionDefinition) Finalize

func (a *ActionDefinition) Finalize()

Finalize inherits security scheme and action responses from parent and top level design.

func (*ActionDefinition) HasAbsoluteRoutes

func (a *ActionDefinition) HasAbsoluteRoutes() bool

HasAbsoluteRoutes returns true if all the action routes are absolute.

func (*ActionDefinition) IterateHeaders

func (a *ActionDefinition) IterateHeaders(it HeaderIterator) error

IterateHeaders iterates over the resource-level and action-level headers, calling the given iterator passing in each response sorted in alphabetical order. Iteration stops if an iterator returns an error and in this case IterateHeaders returns that error.

func (*ActionDefinition) IterateResponses

func (a *ActionDefinition) IterateResponses(it ResponseIterator) error

IterateResponses calls the given iterator passing in each response sorted in alphabetical order. Iteration stops if an iterator returns an error and in this case IterateResponses returns that error.

func (*ActionDefinition) PathParams

func (a *ActionDefinition) PathParams() *AttributeDefinition

PathParams returns the path parameters of the action across all its routes.

func (*ActionDefinition) UserTypes

func (a *ActionDefinition) UserTypes() map[string]*UserTypeDefinition

UserTypes returns all the user types used by the action payload and parameters.

func (*ActionDefinition) Validate

func (a *ActionDefinition) Validate() *dslengine.ValidationErrors

Validate tests whether the action definition is consistent: parameters have unique names and it has at least one response.

func (*ActionDefinition) ValidateParams

func (a *ActionDefinition) ValidateParams() *dslengine.ValidationErrors

ValidateParams checks the action parameters (make sure they have names, members and types).

func (*ActionDefinition) WebSocket

func (a *ActionDefinition) WebSocket() bool

WebSocket returns true if the action scheme is “ws” or “wss” or both (directly or inherited from the resource or API)

type ActionIterator

type ActionIterator func(a *ActionDefinition) error

ActionIterator is the type of functions given to IterateActions.

type Array

type Array struct {
    ElemType *AttributeDefinition
}

Array is the type for a JSON array.

func (*Array) CanHaveDefault

func (a *Array) CanHaveDefault() bool

CanHaveDefault returns true if the array type can have a default value. The array type can have a default value only if the element type can have a default value.

func (*Array) GenerateExample

func (a *Array) GenerateExample(r *RandomGenerator, seen []string) interface{}

GenerateExample produces a random array value.

func (*Array) HasAttributes

func (a *Array) HasAttributes() bool

HasAttributes returns true if the array’s element type is user defined.

func (*Array) IsArray

func (a *Array) IsArray() bool

IsArray returns true.

func (*Array) IsCompatible

func (a *Array) IsCompatible(val interface{}) bool

IsCompatible returns true if val is compatible with p.

func (*Array) IsHash

func (a *Array) IsHash() bool

IsHash returns false.

func (*Array) IsObject

func (a *Array) IsObject() bool

IsObject returns false.

func (*Array) IsPrimitive

func (a *Array) IsPrimitive() bool

IsPrimitive returns false.

func (*Array) Kind

func (a *Array) Kind() Kind

Kind implements DataKind.

func (*Array) MakeSlice

func (a *Array) MakeSlice(s []interface{}) interface{}

MakeSlice examines the key type from the Array and create a slice with builtin type if possible. The idea is to avoid generating []interface{} and produce more known types.

func (*Array) Name

func (a *Array) Name() string

Name returns the type name.

func (*Array) ToArray

func (a *Array) ToArray() *Array

ToArray returns a.

func (*Array) ToHash

func (a *Array) ToHash() *Hash

ToHash returns nil.

func (*Array) ToObject

func (a *Array) ToObject() Object

ToObject returns nil.

type ArrayVal

type ArrayVal []interface{}

ArrayVal is the value of an array used to specify the default value.

func (ArrayVal) ToSlice

func (a ArrayVal) ToSlice() []interface{}

ToSlice converts an ArrayVal to a slice.

type AttributeDefinition

type AttributeDefinition struct {
    // Attribute type
    Type DataType
    // Attribute reference type if any
    Reference DataType
    // Optional description
    Description string
    // Optional validations
    Validation *dslengine.ValidationDefinition
    // Metadata is a list of key/value pairs
    Metadata dslengine.MetadataDefinition
    // Optional member default value
    DefaultValue interface{}
    // Optional member example value
    Example interface{}
    // Optional view used to render Attribute (only applies to media type attributes).
    View string
    // NonZeroAttributes lists the names of the child attributes that cannot have a
    // zero value (and thus whose presence does not need to be validated).
    NonZeroAttributes map[string]bool
    // DSLFunc contains the initialization DSL. This is used for user types.
    DSLFunc func()
}

AttributeDefinition defines a JSON object member with optional description, default value and validations.

func DupAtt

func DupAtt(att *AttributeDefinition) *AttributeDefinition

DupAtt creates a copy of the given attribute.

func (*AttributeDefinition) AddValues

func (a *AttributeDefinition) AddValues(values []interface{})

AddValues adds the Enum values to the attribute’s validation definition. It also performs any conversion needed for HashVal and ArrayVal types.

func (*AttributeDefinition) AllNonZero

func (a *AttributeDefinition) AllNonZero() []string

AllNonZero returns the complete list of all non-zero attribute name.

func (*AttributeDefinition) AllRequired

func (a *AttributeDefinition) AllRequired() (required []string)

AllRequired returns the list of all required fields from the underlying object. An attribute type can be itself an attribute (e.g. a MediaTypeDefinition or a UserTypeDefinition) This happens when the DSL uses references for example. So traverse the hierarchy and collect all the required validations.

func (*AttributeDefinition) Context

func (a *AttributeDefinition) Context() string

Context returns the generic definition name used in error messages.

func (*AttributeDefinition) DSL

func (a *AttributeDefinition) DSL() func()

DSL returns the initialization DSL.

func (*AttributeDefinition) Definition

func (a *AttributeDefinition) Definition() *AttributeDefinition

Definition returns the underlying attribute definition. Note that this function is “inherited” by both UserTypeDefinition and MediaTypeDefinition.

func (*AttributeDefinition) GenerateExample

func (a *AttributeDefinition) GenerateExample(rand *RandomGenerator, seen []string) interface{}

GenerateExample returns the value of the Example field if not nil. Otherwise it traverses the attribute type and recursively generates an example. The result is saved in the Example field.

func (*AttributeDefinition) HasDefaultValue

func (a *AttributeDefinition) HasDefaultValue(attName string) bool

HasDefaultValue returns true if the given attribute has a default value.

func (*AttributeDefinition) Inherit

func (a *AttributeDefinition) Inherit(parent *AttributeDefinition, seen ...map[*AttributeDefinition]struct{})

Inherit merges the properties of existing target type attributes with the argument’s. The algorithm is recursive so that child attributes are also merged.

func (*AttributeDefinition) IsFile

func (a *AttributeDefinition) IsFile(attName string) bool

IsFile returns true if the attribute is of type File or if any its children attributes (if any) is.

func (*AttributeDefinition) IsInterface

func (a *AttributeDefinition) IsInterface(attName string) bool

IsInterface returns true if the field generated for the given attribute has an interface type that should not be referenced as a “*interface{}” pointer. The target attribute must be an object.

func (*AttributeDefinition) IsNonZero

func (a *AttributeDefinition) IsNonZero(attName string) bool

IsNonZero returns true if the given string matches the name of a non-zero attribute, false otherwise.

func (*AttributeDefinition) IsPrimitivePointer

func (a *AttributeDefinition) IsPrimitivePointer(attName string) bool

IsPrimitivePointer returns true if the field generated for the given attribute should be a pointer to a primitive type. The target attribute must be an object.

func (*AttributeDefinition) IsReadOnly

func (a *AttributeDefinition) IsReadOnly() bool

IsReadOnly returns true if attribute is read-only (set using SetReadOnly() method)

func (*AttributeDefinition) IsRequired

func (a *AttributeDefinition) IsRequired(attName string) bool

IsRequired returns true if the given string matches the name of a required attribute, false otherwise.

func (*AttributeDefinition) Merge

func (a *AttributeDefinition) Merge(other *AttributeDefinition) *AttributeDefinition

Merge merges the argument attributes into the target and returns the target overriding existing attributes with identical names. This only applies to attributes of type Object and Merge panics if the argument or the target is not of type Object.

func (*AttributeDefinition) SetDefault

func (a *AttributeDefinition) SetDefault(def interface{})

SetDefault sets the default for the attribute. It also converts HashVal and ArrayVal to map and slice respectively.

func (*AttributeDefinition) SetExample

func (a *AttributeDefinition) SetExample(example interface{}) bool

SetExample sets the custom example. SetExample also handles the case when the user doesn’t want any example or any auto-generated example.

func (*AttributeDefinition) SetReadOnly

func (a *AttributeDefinition) SetReadOnly()

SetReadOnly sets the attribute’s ReadOnly field as true.

func (*AttributeDefinition) Validate

func (a *AttributeDefinition) Validate(ctx string, parent dslengine.Definition) *dslengine.ValidationErrors

Validate tests whether the attribute definition is consistent: required fields exist. Since attributes are unaware of their context, additional context information can be provided to be used in error messages. The parent definition context is automatically added to error messages.

func (*AttributeDefinition) Walk

func (a *AttributeDefinition) Walk(walker func(*AttributeDefinition) error) error

Walk traverses the data structure recursively and calls the given function once on each attribute starting with the attribute returned by Definition.

type AttributeIterator

type AttributeIterator func(string, *AttributeDefinition) error

AttributeIterator is the type of the function given to IterateAttributes.

type ByFilePath

type ByFilePath []*FileServerDefinition

ByFilePath makes FileServerDefinition sortable for code generators.

func (ByFilePath) Len

func (b ByFilePath) Len() int

func (ByFilePath) Less

func (b ByFilePath) Less(i, j int) bool

func (ByFilePath) Swap

func (b ByFilePath) Swap(i, j int)

type CORSDefinition

type CORSDefinition struct {
    // Parent API or resource
    Parent dslengine.Definition
    // Origin
    Origin string
    // List of authorized headers, "*" authorizes all
    Headers []string
    // List of authorized HTTP methods
    Methods []string
    // List of headers exposed to clients
    Exposed []string
    // How long to cache a preflight request response
    MaxAge uint
    // Sets Access-Control-Allow-Credentials header
    Credentials bool
    // Sets Whether the Origin string is a regular expression
    Regexp bool
}

CORSDefinition contains the definition for a specific origin CORS policy.

func (*CORSDefinition) Context

func (cors *CORSDefinition) Context() string

Context returns the generic definition name used in error messages.

func (*CORSDefinition) Validate

func (cors *CORSDefinition) Validate() *dslengine.ValidationErrors

Validate makes sure the CORS definition origin is valid.

type ContactDefinition

type ContactDefinition struct {
    // Name of the contact person/organization
    Name string `json:"name,omitempty"`
    // Email address of the contact person/organization
    Email string `json:"email,omitempty"`
    // URL pointing to the contact information
    URL string `json:"url,omitempty"`
}

ContactDefinition contains the API contact information.

func (*ContactDefinition) Context

func (c *ContactDefinition) Context() string

Context returns the generic definition name used in error messages.

type ContainerDefinition

type ContainerDefinition interface {
    // Attribute returns the container definition embedded attribute.
    Attribute() *AttributeDefinition
}

ContainerDefinition defines a generic container definition that contains attributes. This makes it possible for plugins to use attributes in their own data structures.

type DataStructure

type DataStructure interface {
    // Definition returns the data structure definition.
    Definition() *AttributeDefinition
    // Walk traverses the data structure recursively and calls the given function once
    // on each attribute starting with the attribute returned by Definition.
    // User type and media type attributes are traversed once even for recursive
    // definitions to avoid infinite recursion.
    // Walk stops and returns the error if the function returns a non-nil error.
    Walk(func(*AttributeDefinition) error) error
}

DataStructure is the interface implemented by all data structure types. That is attribute definitions, user types and media types.

type DataType

type DataType interface {
    // Kind of data type, one of the Kind enum.
    Kind() Kind
    // Name returns the type name.
    Name() string
    // IsPrimitive returns true if the underlying type is one of the primitive types.
    IsPrimitive() bool
    // HasAttributes returns true if the underlying type has any attributes.
    HasAttributes() bool
    // IsObject returns true if the underlying type is an object, a user type which
    // is an object or a media type whose type is an object.
    IsObject() bool
    // IsArray returns true if the underlying type is an array, a user type which
    // is an array or a media type whose type is an array.
    IsArray() bool
    // IsHash returns true if the underlying type is a hash map, a user type which
    // is a hash map or a media type whose type is a hash map.
    IsHash() bool
    // ToObject returns the underlying object if any (i.e. if IsObject returns true),
    // nil otherwise.
    ToObject() Object
    // ToArray returns the underlying array if any (i.e. if IsArray returns true),
    // nil otherwise.
    ToArray() *Array
    // ToHash returns the underlying hash map if any (i.e. if IsHash returns true),
    // nil otherwise.
    ToHash() *Hash
    // CanHaveDefault returns whether the data type can have a default value.
    CanHaveDefault() bool
    // IsCompatible checks whether val has a Go type that is
    // compatible with the data type.
    IsCompatible(val interface{}) bool
    // GenerateExample returns a random value for the given data type.
    // If the data type has validations then the example value validates them.
    // seen keeps track of the user and media types that have been traversed via
    // recursion to prevent infinite loops.
    GenerateExample(r *RandomGenerator, seen []string) interface{}
}

DataType is the common interface to all types.

func Dup

func Dup(d DataType) DataType

Dup creates a copy the given data type.

type DocsDefinition

type DocsDefinition struct {
    // Description of documentation.
    Description string `json:"description,omitempty"`
    // URL to documentation.
    URL string `json:"url,omitempty"`
}

DocsDefinition points to external documentation.

func (*DocsDefinition) Context

func (d *DocsDefinition) Context() string

Context returns the generic definition name used in error messages.

type EncodingDefinition

type EncodingDefinition struct {
    // MIMETypes is the set of possible MIME types for the content being encoded or decoded.
    MIMETypes []string
    // PackagePath is the path to the Go package that implements the encoder/decoder.
    // The package must expose a `EncoderFactory` or `DecoderFactory` function
    // that the generated code calls. The methods must return objects that implement
    // the goa.EncoderFactory or goa.DecoderFactory interface respectively.
    PackagePath string
    // Function is the name of the Go function used to instantiate the encoder/decoder.
    // Defaults to NewEncoder and NewDecoder respecitively.
    Function string
    // Encoder is true if the definition is for a encoder, false if it's for a decoder.
    Encoder bool
}

EncodingDefinition defines an encoder supported by the API.

func (*EncodingDefinition) Context

func (enc *EncodingDefinition) Context() string

Context returns the generic definition name used in error messages.

func (*EncodingDefinition) Validate

func (enc *EncodingDefinition) Validate() *dslengine.ValidationErrors

Validate validates the encoding MIME type and Go package path if set.

type FileServerDefinition

type FileServerDefinition struct {
    // Parent resource
    Parent *ResourceDefinition
    // Description for docs
    Description string
    // Docs points to the API external documentation
    Docs *DocsDefinition
    // FilePath is the file path to the static asset(s)
    FilePath string
    // RequestPath is the HTTP path that servers the assets.
    RequestPath string
    // Metadata is a list of key/value pairs
    Metadata dslengine.MetadataDefinition
    // Security defines security requirements for the file server.
    Security *SecurityDefinition
}

FileServerDefinition defines an endpoint that servers static assets.

func (*FileServerDefinition) Context

func (f *FileServerDefinition) Context() string

Context returns the generic definition name used in error messages.

func (*FileServerDefinition) Finalize

func (f *FileServerDefinition) Finalize()

Finalize inherits security scheme from parent and top level design.

func (*FileServerDefinition) IsDir

func (f *FileServerDefinition) IsDir() bool

IsDir returns true if the file server serves a directory, false otherwise.

func (*FileServerDefinition) Validate

func (f *FileServerDefinition) Validate() *dslengine.ValidationErrors

Validate checks the file server is properly initialized.

type FileServerIterator

type FileServerIterator func(f *FileServerDefinition) error

FileServerIterator is the type of functions given to IterateFileServers.

type Hash

type Hash struct {
    KeyType  *AttributeDefinition
    ElemType *AttributeDefinition
}

Hash is the type for a hash map.

func (*Hash) CanHaveDefault

func (h *Hash) CanHaveDefault() bool

CanHaveDefault returns true if the hash type can have a default value. The hash type can have a default value only if both the key type and the element type can have a default value.

func (*Hash) GenerateExample

func (h *Hash) GenerateExample(r *RandomGenerator, seen []string) interface{}

GenerateExample returns a random hash value.

func (*Hash) HasAttributes

func (h *Hash) HasAttributes() bool

HasAttributes returns true if the either hash’s key type is user defined or the element type is user defined.

func (*Hash) IsArray

func (h *Hash) IsArray() bool

IsArray returns false.

func (*Hash) IsCompatible

func (h *Hash) IsCompatible(val interface{}) bool

IsCompatible returns true if val is compatible with p.

func (*Hash) IsHash

func (h *Hash) IsHash() bool

IsHash returns true.

func (*Hash) IsObject

func (h *Hash) IsObject() bool

IsObject returns false.

func (*Hash) IsPrimitive

func (h *Hash) IsPrimitive() bool

IsPrimitive returns false.

func (*Hash) Kind

func (h *Hash) Kind() Kind

Kind implements DataKind.

func (*Hash) MakeMap

func (h *Hash) MakeMap(m map[interface{}]interface{}) interface{}

MakeMap examines the key type from a Hash and create a map with builtin type if possible. The idea is to avoid generating map[interface{}]interface{}, which cannot be handled by json.Marshal.

func (*Hash) Name

func (h *Hash) Name() string

Name returns the type name.

func (*Hash) ToArray

func (h *Hash) ToArray() *Array

ToArray returns nil.

func (*Hash) ToHash

func (h *Hash) ToHash() *Hash

ToHash returns the underlying hash map.

func (*Hash) ToObject

func (h *Hash) ToObject() Object

ToObject returns nil.

type HashVal

type HashVal map[interface{}]interface{}

HashVal is the value of a hash used to specify the default value.

func (HashVal) ToMap

func (h HashVal) ToMap() map[interface{}]interface{}

ToMap converts a HashVal to a map.

type HeaderIterator

type HeaderIterator func(name string, isRequired bool, h *AttributeDefinition) error

HeaderIterator is the type of functions given to IterateHeaders.

type Kind

type Kind uint

A Kind defines the JSON type that a DataType represents.

const (
    // BooleanKind represents a JSON bool.
    BooleanKind Kind = iota + 1
    // IntegerKind represents a JSON integer.
    IntegerKind
    // NumberKind represents a JSON number including integers.
    NumberKind
    // StringKind represents a JSON string.
    StringKind
    // DateTimeKind represents a JSON string that is parsed as a Go time.Time
    DateTimeKind
    // UUIDKind represents a JSON string that is parsed as a Go uuid.UUID
    UUIDKind
    // AnyKind represents a generic interface{}.
    AnyKind
    // ArrayKind represents a JSON array.
    ArrayKind
    // ObjectKind represents a JSON object.
    ObjectKind
    // HashKind represents a JSON object where the keys are not known in advance.
    HashKind
    // UserTypeKind represents a user type.
    UserTypeKind
    // MediaTypeKind represents a media type.
    MediaTypeKind
    // FileKind represents a file.
    FileKind
)

type LicenseDefinition

type LicenseDefinition struct {
    // Name of license used for the API
    Name string `json:"name,omitempty"`
    // URL to the license used for the API
    URL string `json:"url,omitempty"`
}

LicenseDefinition contains the license information for the API.

func (*LicenseDefinition) Context

func (l *LicenseDefinition) Context() string

Context returns the generic definition name used in error messages.

type LinkDefinition

type LinkDefinition struct {
    // Link name
    Name string
    // View used to render link if not "link"
    View string
    // URITemplate is the RFC6570 URI template of the link Href.
    URITemplate string

    // Parent media Type
    Parent *MediaTypeDefinition
}

LinkDefinition defines a media type link, it specifies a URL to a related resource.

func (*LinkDefinition) Attribute

func (l *LinkDefinition) Attribute() *AttributeDefinition

Attribute returns the linked attribute.

func (*LinkDefinition) Context

func (l *LinkDefinition) Context() string

Context returns the generic definition name used in error messages.

func (*LinkDefinition) MediaType

func (l *LinkDefinition) MediaType() *MediaTypeDefinition

MediaType returns the media type of the linked attribute.

func (*LinkDefinition) Validate

func (l *LinkDefinition) Validate() *dslengine.ValidationErrors

Validate checks that the link definition is consistent: it has a media type or the name of an attribute part of the parent media type.

type MediaTypeDefinition

type MediaTypeDefinition struct {
    // A media type is a type
    *UserTypeDefinition
    // Identifier is the RFC 6838 media type identifier.
    Identifier string
    // ContentType identifies the value written to the response "Content-Type" header.
    // Defaults to Identifier.
    ContentType string
    // Links list the rendered links indexed by name.
    Links map[string]*LinkDefinition
    // Views list the supported views indexed by name.
    Views map[string]*ViewDefinition
    // Resource this media type is the canonical representation for if any
    Resource *ResourceDefinition
}

MediaTypeDefinition describes the rendering of a resource using property and link definitions. A property corresponds to a single member of the media type, it has a name and a type as well as optional validation rules. A link has a name and a URL that points to a related resource. Media types also define views which describe which members and links to render when building the response body for the corresponding view.

func NewMediaTypeDefinition

func NewMediaTypeDefinition(name, identifier string, dsl func()) *MediaTypeDefinition

NewMediaTypeDefinition creates a media type definition but does not execute the DSL.

func (*MediaTypeDefinition) ComputeViews

func (m *MediaTypeDefinition) ComputeViews() map[string]*ViewDefinition

ComputeViews returns the media type views recursing as necessary if the media type is a collection.

func (*MediaTypeDefinition) Finalize

func (m *MediaTypeDefinition) Finalize()

Finalize sets the value of ContentType to the identifier if not set.

func (*MediaTypeDefinition) IsError

func (m *MediaTypeDefinition) IsError() bool

IsError returns true if the media type is implemented via a goa struct.

func (*MediaTypeDefinition) IterateViews

func (m *MediaTypeDefinition) IterateViews(it ViewIterator) error

IterateViews calls the given iterator passing in each attribute sorted in alphabetical order. Iteration stops if an iterator returns an error and in this case IterateViews returns that error.

func (*MediaTypeDefinition) Kind

func (m *MediaTypeDefinition) Kind() Kind

Kind implements DataKind.

func (*MediaTypeDefinition) Project

func (m *MediaTypeDefinition) Project(view string) (*MediaTypeDefinition, *UserTypeDefinition, error)

Project creates a MediaTypeDefinition containing the fields defined in the given view. The resuling media type only defines the default view and its identifier is modified to indicate that it was projected by adding the view as id parameter. links is a user type of type Object where each key corresponds to a linked media type as defined by the media type “links” attribute.

func (*MediaTypeDefinition) Validate

func (m *MediaTypeDefinition) Validate() *dslengine.ValidationErrors

Validate checks that the media type definition is consistent: its identifier is a valid media type identifier.

type MediaTypeIterator

type MediaTypeIterator func(m *MediaTypeDefinition) error

MediaTypeIterator is the type of functions given to IterateMediaTypes.

type MediaTypeRoot

type MediaTypeRoot map[string]*MediaTypeDefinition

MediaTypeRoot is the data structure that represents the additional DSL definition root that contains the media type definition set created by CollectionOf index by canonical id.

func (MediaTypeRoot) DSLName

func (r MediaTypeRoot) DSLName() string

DSLName is displayed to the user when the DSL executes.

func (MediaTypeRoot) DependsOn

func (r MediaTypeRoot) DependsOn() []dslengine.Root

DependsOn return the DSL roots the generated media types DSL root depends on, that’s the API DSL.

func (MediaTypeRoot) IterateSets

func (r MediaTypeRoot) IterateSets(iterator dslengine.SetIterator)

IterateSets iterates over the one generated media type definition set.

func (MediaTypeRoot) Reset

func (r MediaTypeRoot) Reset()

Reset deletes all the keys.

type Object

type Object map[string]*AttributeDefinition

Object is the type for a JSON object.

func (Object) CanHaveDefault

func (o Object) CanHaveDefault() bool

CanHaveDefault returns false.

func (Object) GenerateExample

func (o Object) GenerateExample(r *RandomGenerator, seen []string) interface{}

GenerateExample returns a random value of the object.

func (Object) HasAttributes

func (o Object) HasAttributes() bool

HasAttributes returns true.

func (Object) IsArray

func (o Object) IsArray() bool

IsArray returns false.

func (Object) IsCompatible

func (o Object) IsCompatible(val interface{}) bool

IsCompatible returns true if val is compatible with p.

func (Object) IsHash

func (o Object) IsHash() bool

IsHash returns false.

func (Object) IsObject

func (o Object) IsObject() bool

IsObject returns true.

func (Object) IsPrimitive

func (o Object) IsPrimitive() bool

IsPrimitive returns false.

func (Object) IterateAttributes

func (o Object) IterateAttributes(it AttributeIterator) error

IterateAttributes calls the given iterator passing in each attribute sorted in alphabetical order. Iteration stops if an iterator returns an error and in this case IterateObject returns that error.

func (Object) Kind

func (o Object) Kind() Kind

Kind implements DataKind.

func (Object) Merge

func (o Object) Merge(other Object)

Merge copies other’s attributes into o overridding any pre-existing attribute with the same name.

func (Object) Name

func (o Object) Name() string

Name returns the type name.

func (Object) ToArray

func (o Object) ToArray() *Array

ToArray returns nil.

func (Object) ToHash

func (o Object) ToHash() *Hash

ToHash returns nil.

func (Object) ToObject

func (o Object) ToObject() Object

ToObject returns the underlying object.

type Primitive

type Primitive Kind

Primitive is the type for null, boolean, integer, number, string, and time.

func (Primitive) CanHaveDefault

func (p Primitive) CanHaveDefault() (ok bool)

CanHaveDefault returns whether the primitive can have a default value.

func (Primitive) GenerateExample

func (p Primitive) GenerateExample(r *RandomGenerator, seen []string) interface{}

GenerateExample returns an instance of the given data type.

func (Primitive) HasAttributes

func (p Primitive) HasAttributes() bool

HasAttributes returns false.

func (Primitive) IsArray

func (p Primitive) IsArray() bool

IsArray returns false.

func (Primitive) IsCompatible

func (p Primitive) IsCompatible(val interface{}) bool

IsCompatible returns true if val is compatible with p.

func (Primitive) IsHash

func (p Primitive) IsHash() bool

IsHash returns false.

func (Primitive) IsObject

func (p Primitive) IsObject() bool

IsObject returns false.

func (Primitive) IsPrimitive

func (p Primitive) IsPrimitive() bool

IsPrimitive returns true.

func (Primitive) Kind

func (p Primitive) Kind() Kind

Kind implements DataKind.

func (Primitive) Name

func (p Primitive) Name() string

Name returns the JSON type name.

func (Primitive) ToArray

func (p Primitive) ToArray() *Array

ToArray returns nil.

func (Primitive) ToHash

func (p Primitive) ToHash() *Hash

ToHash returns nil.

func (Primitive) ToObject

func (p Primitive) ToObject() Object

ToObject returns nil.

type RandomGenerator

type RandomGenerator struct {
    Seed string
    // contains filtered or unexported fields
}

RandomGenerator generates consistent random values of different types given a seed. The random values are consistent in that given the same seed the same random values get generated.

func NewRandomGenerator

func NewRandomGenerator(seed string) *RandomGenerator

NewRandomGenerator returns a random value generator seeded from the given string value.

func (*RandomGenerator) Bool

func (r *RandomGenerator) Bool() bool

Bool produces a random boolean.

func (*RandomGenerator) DateTime

func (r *RandomGenerator) DateTime() time.Time

DateTime produces a random date.

func (*RandomGenerator) File

func (r *RandomGenerator) File() string

File produces a random file.

func (*RandomGenerator) Float64

func (r *RandomGenerator) Float64() float64

Float64 produces a random float64 value.

func (*RandomGenerator) Int

func (r *RandomGenerator) Int() int

Int produces a random integer.

func (*RandomGenerator) String

func (r *RandomGenerator) String() string

String produces a random string.

func (*RandomGenerator) UUID

func (r *RandomGenerator) UUID() uuid.UUID

UUID produces a random UUID.

type ResourceDefinition

type ResourceDefinition struct {
    // Resource name
    Name string
    // Schemes is the supported API URL schemes
    Schemes []string
    // Common URL prefix to all resource action HTTP requests
    BasePath string
    // Path and query string parameters that apply to all actions.
    Params *AttributeDefinition
    // Name of parent resource if any
    ParentName string
    // Optional description
    Description string
    // Default media type, describes the resource attributes
    MediaType string
    // Default view name if default media type is MediaTypeDefinition
    DefaultViewName string
    // Exposed resource actions indexed by name
    Actions map[string]*ActionDefinition
    // FileServers is the list of static asset serving endpoints
    FileServers []*FileServerDefinition
    // Action with canonical resource path
    CanonicalActionName string
    // Map of response definitions that apply to all actions indexed by name.
    Responses map[string]*ResponseDefinition
    // Request headers that apply to all actions.
    Headers *AttributeDefinition
    // Origins defines the CORS policies that apply to this resource.
    Origins map[string]*CORSDefinition
    // DSLFunc contains the DSL used to create this definition if any.
    DSLFunc func()
    // metadata is a list of key/value pairs
    Metadata dslengine.MetadataDefinition
    // Security defines security requirements for the Resource,
    // for actions that don't define one themselves.
    Security *SecurityDefinition
}

ResourceDefinition describes a REST resource. It defines both a media type and a set of actions that can be executed through HTTP requests.

func NewResourceDefinition

func NewResourceDefinition(name string, dsl func()) *ResourceDefinition

NewResourceDefinition creates a resource definition but does not execute the DSL.

func (*ResourceDefinition) AllOrigins

func (r *ResourceDefinition) AllOrigins() []*CORSDefinition

AllOrigins compute all CORS policies for the resource taking into account any API policy. The result is sorted alphabetically by policy origin.

func (*ResourceDefinition) CanonicalAction

func (r *ResourceDefinition) CanonicalAction() *ActionDefinition

CanonicalAction returns the canonical action of the resource if any. The canonical action is used to compute hrefs to resources.

func (*ResourceDefinition) Context

func (r *ResourceDefinition) Context() string

Context returns the generic definition name used in error messages.

func (*ResourceDefinition) DSL

func (r *ResourceDefinition) DSL() func()

DSL returns the initialization DSL.

func (*ResourceDefinition) Finalize

func (r *ResourceDefinition) Finalize()

Finalize is run post DSL execution. It merges response definitions, creates implicit action parameters, initializes querystring parameters, sets path parameters as non zero attributes and sets the fallbacks for security schemes.

func (*ResourceDefinition) FullPath

func (r *ResourceDefinition) FullPath() string

FullPath computes the base path to the resource actions concatenating the API and parent resource base paths as needed.

func (*ResourceDefinition) IterateActions

func (r *ResourceDefinition) IterateActions(it ActionIterator) error

IterateActions calls the given iterator passing in each resource action sorted in alphabetical order. Iteration stops if an iterator returns an error and in this case IterateActions returns that error.

func (*ResourceDefinition) IterateFileServers

func (r *ResourceDefinition) IterateFileServers(it FileServerIterator) error

IterateFileServers calls the given iterator passing each resource file server sorted by file path. Iteration stops if an iterator returns an error and in this case IterateFileServers returns that error.

func (*ResourceDefinition) IterateHeaders

func (r *ResourceDefinition) IterateHeaders(it HeaderIterator) error

IterateHeaders calls the given iterator passing in each response sorted in alphabetical order. Iteration stops if an iterator returns an error and in this case IterateHeaders returns that error.

func (*ResourceDefinition) Parent

func (r *ResourceDefinition) Parent() *ResourceDefinition

Parent returns the parent resource if any, nil otherwise.

func (*ResourceDefinition) PathParams

func (r *ResourceDefinition) PathParams() *AttributeDefinition

PathParams returns the base path parameters of r.

func (*ResourceDefinition) PreflightPaths

func (r *ResourceDefinition) PreflightPaths() []string

PreflightPaths returns the paths that should handle OPTIONS requests.

func (*ResourceDefinition) URITemplate

func (r *ResourceDefinition) URITemplate() string

URITemplate returns a URI template to this resource. The result is the empty string if the resource does not have a “show” action and does not define a different canonical action.

func (*ResourceDefinition) UserTypes

func (r *ResourceDefinition) UserTypes() map[string]*UserTypeDefinition

UserTypes returns all the user types used by the resource action payloads and parameters.

func (*ResourceDefinition) Validate

func (r *ResourceDefinition) Validate() *dslengine.ValidationErrors

Validate tests whether the resource definition is consistent: action names are valid and each action is valid.

type ResourceIterator

type ResourceIterator func(r *ResourceDefinition) error

ResourceIterator is the type of functions given to IterateResources.

type ResponseDefinition

type ResponseDefinition struct {
    // Response name
    Name string
    // HTTP status
    Status int
    // Response description
    Description string
    // Response body type if any
    Type DataType
    // Response body media type if any
    MediaType string
    // Response view name if MediaType is MediaTypeDefinition
    ViewName string
    // Response header definitions
    Headers *AttributeDefinition
    // Parent action or resource
    Parent dslengine.Definition
    // Metadata is a list of key/value pairs
    Metadata dslengine.MetadataDefinition
    // Standard is true if the response definition comes from the goa default responses
    Standard bool
}

ResponseDefinition defines a HTTP response status and optional validation rules.

func (*ResponseDefinition) Context

func (r *ResponseDefinition) Context() string

Context returns the generic definition name used in error messages.

func (*ResponseDefinition) Dup

func (r *ResponseDefinition) Dup() *ResponseDefinition

Dup returns a copy of the response definition.

func (*ResponseDefinition) Finalize

func (r *ResponseDefinition) Finalize()

Finalize sets the response media type from its type if the type is a media type and no media type is already specified.

func (*ResponseDefinition) Merge

func (r *ResponseDefinition) Merge(other *ResponseDefinition)

Merge merges other into target. Only the fields of target that are not already set are merged.

func (*ResponseDefinition) Validate

func (r *ResponseDefinition) Validate() *dslengine.ValidationErrors

Validate checks that the response definition is consistent: its status is set and the media type definition if any is valid.

type ResponseIterator

type ResponseIterator func(r *ResponseDefinition) error

ResponseIterator is the type of functions given to IterateResponses.

type ResponseTemplateDefinition

type ResponseTemplateDefinition struct {
    // Response template name
    Name string
    // Response template function
    Template func(params ...string) *ResponseDefinition
}

ResponseTemplateDefinition defines a response template. A response template is a function that takes an arbitrary number of strings and returns a response definition.

func (*ResponseTemplateDefinition) Context

func (r *ResponseTemplateDefinition) Context() string

Context returns the generic definition name used in error messages.

type RouteDefinition

type RouteDefinition struct {
    // Verb is the HTTP method, e.g. "GET", "POST", etc.
    Verb string
    // Path is the URL path e.g. "/tasks/:id"
    Path string
    // Parent is the action this route applies to.
    Parent *ActionDefinition
    // Metadata is a list of key/value pairs
    Metadata dslengine.MetadataDefinition
}

RouteDefinition represents an action route.

func (*RouteDefinition) Context

func (r *RouteDefinition) Context() string

Context returns the generic definition name used in error messages.

func (*RouteDefinition) FullPath

func (r *RouteDefinition) FullPath() string

FullPath returns the action full path computed by concatenating the API and resource base paths with the action specific path.

func (*RouteDefinition) IsAbsolute

func (r *RouteDefinition) IsAbsolute() bool

IsAbsolute returns true if the action path should not be concatenated to the resource and API base paths.

func (*RouteDefinition) Params

func (r *RouteDefinition) Params() []string

Params returns the route parameters. For example for the route “GET /foo/:fooID” Params returns []string{“fooID”}.

func (*RouteDefinition) Validate

func (r *RouteDefinition) Validate() *dslengine.ValidationErrors

Validate checks that the route definition is consistent: it has a parent.

type SecurityDefinition

type SecurityDefinition struct {
    // Scheme defines the Security Scheme used for this action.
    Scheme *SecuritySchemeDefinition

    // Scopes are scopes required for this action
    Scopes []string `json:"scopes,omitempty"`
}

SecurityDefinition defines security requirements for an Action

func (*SecurityDefinition) Context

func (s *SecurityDefinition) Context() string

Context returns the generic definition name used in error messages.

type SecuritySchemeDefinition

type SecuritySchemeDefinition struct {
    // Kind is the sort of security scheme this object represents
    Kind SecuritySchemeKind
    // DSLFunc is an optional DSL function
    DSLFunc func()

    // Scheme is the name of the security scheme, referenced in
    // Security() declarations. Ex: "googAuth", "my_big_token", "jwt".
    SchemeName string `json:"scheme"`

    // Type is one of "apiKey", "oauth2" or "basic", according to the
    // Swagger specs. We also support "jwt".
    Type string `json:"type"`
    // Description describes the security scheme. Ex: "Google OAuth2"
    Description string `json:"description"`
    // In determines whether it is in the "header" or in the "query"
    // string that we will find an `apiKey`.
    In string `json:"in,omitempty"`
    // Name refers to a header or parameter name, based on In's value.
    Name string `json:"name,omitempty"`
    // Scopes is a list of available scopes for this scheme, along
    // with their textual description.
    Scopes map[string]string `json:"scopes,omitempty"`
    // Flow determines the oauth2 flow to use for this scheme.
    Flow string `json:"flow,omitempty"`
    // TokenURL holds the URL for refreshing tokens with oauth2 or JWT
    TokenURL string `json:"token_url,omitempty"`
    // AuthorizationURL holds URL for retrieving authorization codes with oauth2
    AuthorizationURL string `json:"authorization_url,omitempty"`
    // Metadata is a list of key/value pairs
    Metadata dslengine.MetadataDefinition
}

SecuritySchemeDefinition defines a security scheme used to authenticate against the API being designed. See http://swagger.io/specification/#securityDefinitionsObject for more information.

func (*SecuritySchemeDefinition) Context

func (s *SecuritySchemeDefinition) Context() string

Context returns the generic definition name used in error messages.

func (*SecuritySchemeDefinition) DSL

func (s *SecuritySchemeDefinition) DSL() func()

DSL returns the DSL function

func (*SecuritySchemeDefinition) Finalize

func (s *SecuritySchemeDefinition) Finalize()

Finalize makes the TokenURL and AuthorizationURL complete if needed.

func (*SecuritySchemeDefinition) Validate

func (s *SecuritySchemeDefinition) Validate() error

Validate ensures that TokenURL and AuthorizationURL are valid URLs.

type SecuritySchemeKind

type SecuritySchemeKind int

SecuritySchemeKind is a type of security scheme, according to the swagger specs.

const (
    // OAuth2SecurityKind means "oauth2" security type.
    OAuth2SecurityKind SecuritySchemeKind = iota + 1
    // BasicAuthSecurityKind means "basic" security type.
    BasicAuthSecurityKind
    // APIKeySecurityKind means "apiKey" security type.
    APIKeySecurityKind
    // JWTSecurityKind means an "apiKey" security type, with support for TokenPath and Scopes.
    JWTSecurityKind
    // NoSecurityKind means to have no security for this endpoint.
    NoSecurityKind
)

type UserTypeDefinition

type UserTypeDefinition struct {
    // A user type is an attribute definition.
    *AttributeDefinition
    // Name of type
    TypeName string
}

UserTypeDefinition is the type for user defined types that are not media types (e.g. payload types).

func NewUserTypeDefinition

func NewUserTypeDefinition(name string, dsl func()) *UserTypeDefinition

NewUserTypeDefinition creates a user type definition but does not execute the DSL.

func (*UserTypeDefinition) CanHaveDefault

func (u *UserTypeDefinition) CanHaveDefault() bool

CanHaveDefault calls CanHaveDefault on the user type underlying data type.

func (*UserTypeDefinition) Context

func (t *UserTypeDefinition) Context() string

Context returns the generic definition name used in error messages.

func (*UserTypeDefinition) DSL

func (t *UserTypeDefinition) DSL() func()

DSL returns the initialization DSL.

func (*UserTypeDefinition) Finalize

func (u *UserTypeDefinition) Finalize()

Finalize merges base type attributes.

func (*UserTypeDefinition) HasAttributes

func (u *UserTypeDefinition) HasAttributes() bool

HasAttributes calls the HasAttributes on the user type underlying data type.

func (*UserTypeDefinition) IsArray

func (u *UserTypeDefinition) IsArray() bool

IsArray calls IsArray on the user type underlying data type.

func (*UserTypeDefinition) IsCompatible

func (u *UserTypeDefinition) IsCompatible(val interface{}) bool

IsCompatible returns true if val is compatible with u.

func (*UserTypeDefinition) IsHash

func (u *UserTypeDefinition) IsHash() bool

IsHash calls IsHash on the user type underlying data type.

func (*UserTypeDefinition) IsObject

func (u *UserTypeDefinition) IsObject() bool

IsObject calls IsObject on the user type underlying data type.

func (*UserTypeDefinition) IsPrimitive

func (u *UserTypeDefinition) IsPrimitive() bool

IsPrimitive calls IsPrimitive on the user type underlying data type.

func (*UserTypeDefinition) Kind

func (u *UserTypeDefinition) Kind() Kind

Kind implements DataKind.

func (*UserTypeDefinition) Name

func (u *UserTypeDefinition) Name() string

Name returns the JSON type name.

func (*UserTypeDefinition) ToArray

func (u *UserTypeDefinition) ToArray() *Array

ToArray calls ToArray on the user type underlying data type.

func (*UserTypeDefinition) ToHash

func (u *UserTypeDefinition) ToHash() *Hash

ToHash calls ToHash on the user type underlying data type.

func (*UserTypeDefinition) ToObject

func (u *UserTypeDefinition) ToObject() Object

ToObject calls ToObject on the user type underlying data type.

func (*UserTypeDefinition) Validate

func (u *UserTypeDefinition) Validate(ctx string, parent dslengine.Definition) *dslengine.ValidationErrors

Validate checks that the user type definition is consistent: it has a name and the attribute backing the type is valid.

func (*UserTypeDefinition) Walk

func (u *UserTypeDefinition) Walk(walker func(*AttributeDefinition) error) error

Walk traverses the data structure recursively and calls the given function once on each attribute starting with the attribute returned by Definition.

type UserTypeIterator

type UserTypeIterator func(m *UserTypeDefinition) error

UserTypeIterator is the type of functions given to IterateUserTypes.

type ViewDefinition

type ViewDefinition struct {
    // Set of properties included in view
    *AttributeDefinition
    // Name of view
    Name string
    // Parent media Type
    Parent *MediaTypeDefinition
}

ViewDefinition defines which members and links to render when building a response. The view is a JSON object whose property names must match the names of the parent media type members. The members fields are inherited from the parent media type but may be overridden.

func (*ViewDefinition) Context

func (v *ViewDefinition) Context() string

Context returns the generic definition name used in error messages.

func (*ViewDefinition) Validate

func (v *ViewDefinition) Validate() *dslengine.ValidationErrors

Validate checks that the view definition is consistent: it has a parent media type and the underlying definition type is consistent.

type ViewIterator

type ViewIterator func(*ViewDefinition) error

ViewIterator is the type of the function given to IterateViews.

Generated by godoc2md