`example` tag support for `map[string]SomeStruct` fields

Is your feature request related to a problem? Please describe.

Fields typed as map[string]SomeStruct have never been able to carry an example tag. There are two failure modes depending on what is written:

No example tag — swaggo generates a correct additionalProperties: $ref schema, but without any example value. Swagger UI and similar renderers show "languages": {} — an empty object that gives readers no idea what the values look like.

Any example tag — the key:value comma parser in defineTypeOfExample is reached with arrayType="object". For a plain string like example:"en", the split produces a single token with no :, and parsing fails:

example value en should format: key:value

Even a syntactically correct key:value pair fails, because the value side recursively calls defineTypeOfExample("object", "", ...) which immediately hits the arrayType == "" guard and errors.

This has been open since 2019 (#327) and affects any API that uses map[string]Struct — localisation maps, dynamic property bags, language-keyed responses, etc.

Describe the solution you'd like

Two new behaviours, both opt-in via the existing example struct tag.

Form 1 — Explicit JSON

Translations map[string]Message `json:"translations" example:"{\"en\":{\"text\":\"Hello\",\"locale\":\"en-US\"}}"`

If the tag value is valid JSON it is used verbatim as the example. This is equivalent to how example works for all other types.

Form 2 — Key name + auto-synthesis

Translations map[string]Message `json:"translations" example:"en"`

If the tag value is a plain string (not JSON), it is used as the map key and the value is synthesised from the example tags already present on Message's fields — including nested []Struct array properties, which are synthesised as single-element slices.

type Message struct {
    Text   string `json:"text"   example:"Hello"`
    Locale string `json:"locale" example:"en-US"`
}

Generates:

"translations": {
  "example": {
    "en": {
      "text": "Hello",
      "locale": "en-US"
    }
  }
}

If no example tag is present, no example is injected. Existing code with map[string]Struct fields and no example tag is completely unaffected.

Backward compatibility:

• No implicit behaviour change. Synthesis only fires when an example tag is present.
• No new errors. The previous hard parse error on any example tag on a map[string]Struct field is replaced by meaningful behaviour.
• Existing map[string]string and swaggertype:"object,string" paths are unchanged — they never hit the arrayType=object branch.

Describe alternatives you've considered

• Explicit JSON only (Form 1 without Form 2). Works, but is verbose and error-prone to hand-write for nested structs, and duplicates the example values already declared on the struct's own fields.
• swaggertype:"object,object" with key:value example syntax (as in #2018). The comma/key:value grammar cannot represent nested struct values, so it can only ever express empty {} values — not a usable example.

Additional context

Related issues:

• #327 — original report, map[string]interface{} example panic (open since 2019)
• #2018 — same defineTypeOfExample error triggered via swaggertype:"object,object" example:"key1:{},key2:{}"
• #2111 — open PR that adds a narrow fix for the empty {} value case in #2018; does not address map[string]SomeStruct field synthesis

Known limitation — named map type aliases are not supported by the key-hint synthesis:

type LangMap map[string]Message  // named alias

type Response struct {
    Langs LangMap `json:"langs" example:"en"`  // synthesis does not fire
}

When the field type is a named alias, the schema is resolved to a $ref before ComplementSchema reaches the synthesis block. This is a pre-existing architectural constraint that affects all field complementation on named map aliases, not specific to this change. Explicit JSON (Form 1) still works in this case.