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  }