github.com/ccrossley/goa@v1.3.1/design/apidsl/metadata.go (about) 1 package apidsl 2 3 import ( 4 "github.com/goadesign/goa/design" 5 "github.com/goadesign/goa/dslengine" 6 ) 7 8 // Metadata is a set of key/value pairs that can be assigned to an object. Each value consists of a 9 // slice of strings so that multiple invocation of the Metadata function on the same target using 10 // the same key builds up the slice. Metadata may be set on attributes, media types, actions, 11 // responses, resources and API definitions. 12 // 13 // While keys can have any value the following names are handled explicitly by goagen when set on 14 // attributes. 15 // 16 // `struct:field:name`: overrides the Go struct field name generated by default by goagen. 17 // Applicable to attributes only. 18 // 19 // Metadata("struct:field:name", "MyName") 20 // 21 // `struct:field:type`: overrides the Go struct field type generated by default by goagen. 22 // The second optional tag value specifies the Go import path to the package defining the 23 // type if not built-in. Applicable to attributes only. 24 // 25 // Metadata("struct:field:type", "[]byte") 26 // Metadata("struct:field:type", "json.RawMessage", "encoding/json") 27 // Metadata("struct:field:type", "mypackage.MyType", "github.com/me/mypackage") 28 // 29 // `struct:tag:xxx`: sets the struct field tag xxx on generated Go structs. Overrides tags that 30 // goagen would otherwise set. If the metadata value is a slice then the strings are joined with 31 // the space character as separator. 32 // Applicable to attributes only. 33 // 34 // Metadata("struct:tag:json", "myName,omitempty") 35 // Metadata("struct:tag:xml", "myName,attr") 36 // 37 // `swagger:generate`: specifies whether Swagger specification should be generated. Defaults to 38 // true. 39 // Applicable to resources, actions and file servers. 40 // 41 // Metadata("swagger:generate", "false") 42 // 43 // `swagger:summary`: sets the Swagger operation summary field. 44 // Applicable to actions. 45 // 46 // Metadata("swagger:summary", "Short summary of what action does") 47 // 48 // `swagger:tag:xxx`: sets the Swagger object field tag xxx. 49 // Applicable to resources and actions. 50 // 51 // Metadata("swagger:tag:Backend") 52 // Metadata("swagger:tag:Backend:desc", "Quick description of what 'Backend' is") 53 // Metadata("swagger:tag:Backend:url", "http://example.com") 54 // Metadata("swagger:tag:Backend:url:desc", "See more docs here") 55 // 56 // `swagger:extension:xxx`: sets the Swagger extensions xxx. It can have any valid JSON format value. 57 // Applicable to 58 // api as within the info and tag object, 59 // resource as within the paths object, 60 // action as within the path-item object, 61 // route as within the operation object, 62 // param as within the parameter object, 63 // response as within the response object 64 // and security as within the security-scheme object. 65 // See https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/EXTENSIONS.md. 66 // 67 // Metadata("swagger:extension:x-api", `{"foo":"bar"}`) 68 // 69 // The special key names listed above may be used as follows: 70 // 71 // var Account = Type("Account", func() { 72 // Attribute("service", String, "Name of service", func() { 73 // // Override default name to avoid clash with built-in 'Service' field. 74 // Metadata("struct:field:name", "ServiceName") 75 // }) 76 // }) 77 // 78 func Metadata(name string, value ...string) { 79 appendMetadata := func(metadata dslengine.MetadataDefinition, name string, value ...string) dslengine.MetadataDefinition { 80 if metadata == nil { 81 metadata = make(map[string][]string) 82 } 83 metadata[name] = append(metadata[name], value...) 84 return metadata 85 } 86 87 switch def := dslengine.CurrentDefinition().(type) { 88 case design.ContainerDefinition: 89 att := def.Attribute() 90 att.Metadata = appendMetadata(att.Metadata, name, value...) 91 case *design.AttributeDefinition: 92 def.Metadata = appendMetadata(def.Metadata, name, value...) 93 case *design.MediaTypeDefinition: 94 def.Metadata = appendMetadata(def.Metadata, name, value...) 95 case *design.ActionDefinition: 96 def.Metadata = appendMetadata(def.Metadata, name, value...) 97 case *design.FileServerDefinition: 98 def.Metadata = appendMetadata(def.Metadata, name, value...) 99 case *design.ResourceDefinition: 100 def.Metadata = appendMetadata(def.Metadata, name, value...) 101 case *design.ResponseDefinition: 102 def.Metadata = appendMetadata(def.Metadata, name, value...) 103 case *design.APIDefinition: 104 def.Metadata = appendMetadata(def.Metadata, name, value...) 105 case *design.RouteDefinition: 106 def.Metadata = appendMetadata(def.Metadata, name, value...) 107 case *design.SecurityDefinition: 108 def.Scheme.Metadata = appendMetadata(def.Scheme.Metadata, name, value...) 109 default: 110 dslengine.IncompatibleDSL() 111 } 112 }