swagger:name

Usage

// swagger:name IDENT_NAME

What it does

Overrides the JSON property name that a struct field or interface method renders as.

By default the scanner derives names from json:"…" struct tags (or the Go identifier for fields / methods with no tag); swagger:name overrides that derivation when the tag-based shape isn’t appropriate — typically on interface methods, which cannot carry struct tags.

Where it goes

On a struct field doc OR an interface method doc.

Grammar (EBNF)

NameAnnotation = ANN_NAME , IDENT_NAME ;

The required IDENT_NAME is the JSON property name to use.

Supported keywords

None — the override name is the entire surface.

Example

On an interface method, swagger:name overrides the property name the method would otherwise publish under (PascalCase Go method name) with the chosen JSON name:

Annotated Go

// Car is exposed as a schema via its method set. Interface methods cannot carry
// a json tag, so by default each property takes the camelCased method name;
// swagger:name overrides that where the default is not what you want.
//
// swagger:model
type Car interface {
	// Maker is the manufacturer. With no override the property is the
	// camelCased method name, "maker".
	Maker() string

	// StructType is the polymorphic class. Without the override the property
	// would be "structType"; swagger:name publishes it as "jsonClass".
	//
	// swagger:name jsonClass
	StructType() string
}


// Account shows the universal name: keyword renaming model struct fields. The
// same keyword used on parameters and response headers also sets a property key
// here, winning over a json tag, the legacy swagger:name annotation, and the Go
// field name.
//
// swagger:model
type Account struct {
	// Bal has no json tag; the keyword sets the property key directly.
	//
	// name: balance
	Bal float64

	// Currency carries both naming forms; the keyword wins over the
	// legacy annotation and the json tag.
	//
	// name: currencyCode
	// swagger:name legacyCurrency
	Currency string `json:"currency"`
}

Full source: docs/examples/concepts/models/models.go

Generated spec

{
  "description": "Car is exposed as a schema via its method set. Interface methods cannot carry\na json tag, so by default each property takes the camelCased method name;",
  "type": "object",
  "properties": {
    "jsonClass": {
      "description": "StructType is the polymorphic class. Without the override the property\nwould be \"structType\"; swagger:name publishes it as \"jsonClass\".",
      "type": "string",
      "x-go-name": "StructType"
    },
    "maker": {
      "description": "Maker is the manufacturer. With no override the property is the\ncamelCased method name, \"maker\".",
      "type": "string",
      "x-go-name": "Maker"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

Full source: docs/examples/concepts/models/testdata/name.json

Full example. fixtures/enhancements/interface-methods/types.go.

Deprecated / legacy forms

swagger:name is the legacy annotation form. The canonical, universal field-naming mechanism is the name: keyword, which works at every field site — model properties, interface methods, parameters, and response headers — with the precedence name: > swagger:name > json: tag > Go field name. swagger:name remains honoured (and idiomatic on interface methods, shown above), but reach for name: in new code; it is the only form that works on parameters and headers.