swagger:omit

Usage

// swagger:omit <field>[,<field>…]

What it does

Stops the named fields being promoted out of an embedded type, so they never reach the enclosing schema.

Embedding a shared type is how Go reuses a struct, but the reused type often carries more than one particular endpoint should: server-assigned fields on a create request, or a field the enclosing struct re-declares for itself. swagger:omit is how the author resolves that — codescan does not guess which fields were meant, it documents the type as written unless told otherwise.

Names are Go field names, never JSON aliases: the annotation acts before names are computed, so it is indifferent to json tags and to NameFromTags.

It is a pre-filter, not an edit of the finished schema. That is what makes it read the same whether the embed is inlined or composed into an allOf member (see Composing embeds with allOf): the field is simply never written.

Where it goes

Two placements:

• on the embed — targets are plain field names of that embedded type. This is the ergonomic form and needs no qualification;
• on the type declaration — for an embed you cannot annotate (a type you do not own, or one nested deeper). A bare name resolves against the promoted set; a dotted path names the embed chain, Base.ID or Outer.Inner.Deep.

// swagger:omit Base.ID,Created
type Decorated struct {
	Base
	// …
}

Embeds only. Every path segment but the last must name an embedded field: swagger:omit removes promoted content, which is the only thing the enclosing schema owns. To exclude a struct’s own field, use swagger:ignore on the field itself.

Grammar (EBNF)

OmitBlock  = ANN_OMIT , OmitTarget , { "," , OmitTarget } ;
OmitTarget = GoIdent , { "." , GoIdent } ;

The whole remainder of the line is the argument list; spaces after commas are allowed (swagger:omit ID, Created).

Supported keywords

None. swagger:omit is a classifier: it takes arguments and opens no keyword block.

Example

The go-swagger#1992 shape: a request body embeds the shared domain type, and the server-assigned fields are dropped from this body only.

// CreateUserParams is the request body: the same User, minus the fields the
// server assigns. `swagger:omit` sits on the embed, so the targets are plain
// field names of the embedded type.
//
// swagger:parameters createUser
type CreateUserParams struct {
	// in: body
	Body struct {
		// swagger:omit ID,Created
		User
	}
}

{
  "type": "object",
  "properties": {
    "Name": {
      "type": "string"
    }
  }
}

The shared type is never touched, so its own definition — which the response $refs — still documents every field:

{
  "description": "The point of the idiom is that you do not have to touch it.",
  "type": "object",
  "title": "User is the shared domain type — deliberately free of any swagger annotation.",
  "properties": {
    "Created": {
      "type": "string",
      "format": "date-time"
    },
    "ID": {
      "type": "integer",
      "format": "int64"
    },
    "Name": {
      "type": "string"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/omit"
}

Full source: docs/examples/concepts/omit/testdata/user.json

Diagnostics

All three are Hints — informational, never blocking:

swagger:omit is the only annotation whose output depends on a name the Go compiler never checks; everything else codescan emits is derived from types. scan.omit-unresolved is what stops it rotting silently when a field is renamed upstream, so wire OnDiagnostic if you rely on the annotation.

Deprecated

No. Added in v0.37.