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, so it reads 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 reports it when a field is renamed upstream, instead of letting the annotation rot silently, so wire OnDiagnostic if you rely on the annotation.

Deprecated

No. Added in v0.37.