📖 2 min read (~ 300 words).

Other type decorators

Beyond validations, a couple of keyword decorators annotate a property’s or operation’s role. The panes below pair the annotated Go with the fragment the scanner emits, from the test-covered docs/examples/concepts/decorators package.

For the value shapes and legal contexts of each, see the Keyword reference.

readOnly

read only: true on a model field marks the property readOnly — the server sets it, clients must not.

Annotated Go
// Token is issued by the server.
//
// swagger:model
type Token struct {
	// ID is assigned by the server and cannot be set by clients.
	//
	// read only: true
	ID string `json:"id"`

	// Value is the token value.
	Value string `json:"value"`
}

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

#/definitions/Token
{
  "type": "object",
  "title": "Token is issued by the server.",
  "properties": {
    "id": {
      "description": "ID is assigned by the server and cannot be set by clients.",
      "type": "string",
      "x-go-name": "ID",
      "readOnly": true
    },
    "value": {
      "description": "Value is the token value.",
      "type": "string",
      "x-go-name": "Value"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/decorators"
}

Full source: docs/examples/concepts/decorators/testdata/readonly.json

deprecated

deprecated: true in a swagger:route / swagger:operation body marks the operation deprecated.

Annotated Go
// swagger:route GET /legacy/ping legacy ping
//
// Ping is the legacy health check.
//
// deprecated: true
//
// responses:
//
//	200: pingResponse

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

paths[/legacy/ping]
{
  "get": {
    "tags": [
      "legacy"
    ],
    "summary": "Ping is the legacy health check.",
    "operationId": "ping",
    "deprecated": true,
    "responses": {
      "200": {
        "$ref": "#/responses/pingResponse"
      }
    }
  }
}

Full source: docs/examples/concepts/decorators/testdata/deprecated.json

Info

deprecated is an operation-level flag in OpenAPI 2.0. The Schema object has no native deprecated, so deprecated: on a model field is not emitted on the property (and produces no x-deprecated).

What’s next