Annotation Reference

Annotations Summary

Annotation	Usage Location	Description
WithSkip	schemaedgefield	Sets the schema, edge, or field to be skipped in the REST API.
WithReadOnly	field	Sets the field to be read-only in the REST API.
WithExample	field	Sets the OpenAPI example for the specified field.
WithEagerLoad	edge	Sets the edge to be eager-loaded in the REST API for each associated entity.
WithSortable	field	Sets the field to be sortable in the REST API.
WithDefaultSort	schema	Sets the default sort field for the schema in the REST API.
WithDefaultOrder	schema	Sets the default sorting order for the schema in the REST API.
WithFilter	schemaedgefield	Sets the field to be filterable with the provided predicate(s).
WithFilterGroup	edgefield	Adds the field to a group of other fields that are filtered together.
WithSchema	field	Sets the OpenAPI schema for the specified field.
WithPagination	schemaedge	Sets the schema to be paginated in the REST API.
WithAllowClientIDs	schema	Sets the schema to allow clients to provide IDs in the CREATE payload.
WithOperationSummary	schemaedge	Provides an OpenAPI summary for the specified operation.
WithOperationDescription	schemaedge	Provides an OpenAPI description for the specified operation.
WithAdditionalTags	schemaedge	Adds additional tags to all operations for this schema/edge.
WithTags	schemaedge	Sets the tags for all operations for this schema/edge.
WithOperationID	schemaedge	Provides an OpenAPI operation ID for the specified operation.
WithDescription	schemaedgefield	Sets the OpenAPI description for the specified schema/edge.
WithMinItemsPerPage	schemaedge	Sets an explicit minimum number of items per page for paginated calls.
WithMaxItemsPerPage	schemaedge	Sets an explicit maximum number of items per page for paginated calls.
WithItemsPerPage	schemaedge	Sets an explicit default number of items per page for paginated calls.
WithEagerLoadLimit	edge	Sets the limit for the max number of entities to eager-load for the edge.
WithEdgeEndpoint	edge	Sets the edge to have an endpoint.
WithEdgeUpdateBulk	edge	Sets the edge to be bulk updated on the entities associated with the edge.
WithHandler	schemaedge	Sets the schema/edge to be an HTTP handler generated for it.
WithDeprecated	schemaedgefield	Sets the OpenAPI deprecated flag for the specified schema/edge/field.
WithIncludeOperations	schemaedge	Includes the specified operations in the REST API for the schema.
WithExcludeOperations	schemaedge	Excludes the specified operations in the REST API for the schema.

`WithSkip`

[ pkg.go.dev | usage: schemaedgefield ]

Sets the schema, edge, or field to be skipped in the REST API. Primarily useful if an entire schema shouldn't be queryable, or if there is a sensitive field that should never be returned (but sensitive isn't set on the field for some reason).

Example

func (Pet) Fields() []ent.Field {
    return []ent.Field{
        field.String("some_sensitive_field").Annotations(
            entrest.WithSkip(true),
        ),
    }
}

`WithReadOnly`

[ pkg.go.dev | usage: field ]

Sets the field to be read-only in the REST API. If you want to make a schema or edge read-only, use the Operations annotation instead.

Example

func (Pet) Fields() []ent.Field {
    return []ent.Field{
        field.String("uuid").Annotations(
            entrest.WithReadOnly(true),
        ),
    }
}

`WithExample`

[ pkg.go.dev | usage: field ]

Sets the OpenAPI example for the specified field. This is recommended if it's not obvious what the fields purpose is, or what the format could be. Many OpenAPI documentation browsers will use this information as an example value within the POST/PATCH body.

Example

func (Pet) Fields() []ent.Field {
    return []ent.Field{
        field.String("uuid").Annotations(
            entrest.WithExample("123e4567-e89b-12d3-a456-426655440000"),
        ),
    }
}

`WithEagerLoad`

[ pkg.go.dev | usage: edge ]

Sets the edge to be eager-loaded in the REST API for each associated entity. Note that edges are not eager-loaded by default. Eager-loading, when enabled, means that the configured edge is always fetched when the parent entity is fetched (only covering the first level, it does not recurse).

See Eager Loading for more information. See also EntGo: Eager Loading.

Example

func (Pet) Edges() []ent.Edge {
    return []ent.Edge{
        edge.To("owner", User.Type).Annotations(
            entrest.WithEagerLoad(true),
        ),
    }
}

`WithSortable`

[ pkg.go.dev | usage: field ]

Sets the field to be sortable in the REST API. Note that only types that can be sorted, will be sortable.

Example

func (Pet) Fields() []ent.Field {
    return []ent.Field{
        field.String("name").Annotations(
            entrest.WithSortable(true),
        ),
    }
}

`WithDefaultSort`

[ pkg.go.dev | usage: schema ]

Sets the default sort field for the schema in the REST API. If not specified, will default to the id field (if it exists on the schema/edge). The provided field must exist on the schema, otherwise codegen will fail. You may provide any of the typical fields shown for the sort field in the OpenAPI specification for this schema. E.g. id, created_at, someedge.count (<edge>.<edge-field>), etc.

Note that this will also change the way eager-loaded edges which are based on this schema are sorted. This is currently the only way to sort eager-loaded data.

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithDefaultSort("name"), // MUST be a valid field!
    }
}

`WithDefaultOrder`

[ pkg.go.dev | usage: schema ]

Sets the default sorting order for the schema in the REST API. If not specified, will default to ASC.

Note that this will also change the way eager-loaded edges which are based on this schema are sorted. This is currently the only way to sort eager-loaded data.

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithDefaultOrder(entrest.OrderDesc),
    }
}

`WithFilter`

[ pkg.go.dev | usage: schemaedgefield ]

Sets the field to be filterable with the provided predicate(s). When applied on an edge with entrest.FilterEdge applied, it will include the fields associated with the edge that are also filterable.

See all predicate constants that can be used with entrest.WithFilter for more information.

Example 1

func (Pet) Fields() []ent.Field {
    return []ent.Field{
        field.String("name").Annotations(
            entrest.WithFilter(entrest.FilterGroupArray | entrest.FilterGroupLength) // Bundle using groups.
        ),
    }
}

Example 2

func (Pet) Fields() []ent.Field {
    return []ent.Field{
        field.String("name").Annotations(
            entrest.WithFilter(entrest.FilterEQ | entrest.FilterNEQ), // Or use individual predicates.
        ),
    }
}

`WithFilterGroup`

[ pkg.go.dev | usage: edgefield ]

Adds the field to a group of other fields that are filtered together. Note that only common filter options across all of the groups will be supported. The goal of this is to group common fields that would be searched together.

You can also use WithFilterGroup on edges to also allow any matching groups on the edge to be included in this filter group. The group name must match when used on the edge if you want that edge to be included in that group.

Example

Using the following annotations:

func (User) Fields() []ent.Field {
    return []ent.Field{
        field.String("username").Annotations(
            entrest.WithFilter(entrest.FilterGroupEqual|entrest.FilterGroupArray),
            entrest.WithFilterGroup("search"),
        ),
        field.String("display_name").Annotations(
            entrest.WithFilter(entrest.FilterGroupEqual|entrest.FilterGroupArray),
            entrest.WithFilterGroup("search"),
        ),
        field.String("email").Annotations(
            entrest.WithFilter(entrest.FilterGroupEqual|entrest.FilterGroupArray),
            entrest.WithFilterGroup("search"),
        ),
        field.Enum("type").
            NamedValues(
                "System", "SYSTEM",
                "User", "USER",
            ).
            Default("USER").
            Annotations(
                entrest.WithExample("USER"),
                entrest.WithFilter(entrest.FilterGroupEqualExact|entrest.FilterGroupArray),
            ),
    }
}

And the following API query:

GET /users?type.eq=USER&search.ihas=foo

This would effectively result in the following psuedo-code being used behind the scenes:

and(type.eq==USER, or(username.ihas==foo, display_name.ihas==foo, email.ihas==foo))

`WithSchema`

[ pkg.go.dev | usage: field ]

Sets the OpenAPI schema for a field. This is required for any fields which are JSON based, or don't have a pre-defined ent type for the field.

You can use entrest.SchemaObjectAny for an object with any properties (effectively any).

Example

func (Pet) Fields() []ent.Field {
    return []ent.Field{
        field.JSON("uuid", &uuid.UUID{}).Annotations(
            entrest.WithSchema(ogen.String()), // Can also use &ogen.Schema{} for full customization.
        ),
    }
}

`WithPagination`

[ pkg.go.dev | usage: schemaedge ]

Sets the schema to be paginated in the REST API. This is not required to be provided unless pagination was disabled globally.

See Pagination for more information.

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithPagination(true),
    }
}

`WithAllowClientIDs`

[ pkg.go.dev | usage: schema ]

Sets the schema to allow clients to provide IDs in the CREATE payload. This is beneficial to allow the client to supply UUIDs as primary keys (for idempotency), or when your ID field is a username, for example. This is not required if Config.AllowClientIDs is enabled.

SECURITY NOTE: allowing requests to include the ID field is not recommended, unless you add necessary validation (permissions) or disallow resources from being deleted. Otherwise, you may allow an attacker to spoof a previously deleted resource, leading to takeover attack vectors.

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithAllowClientIDs(true),
    }
}

`WithOperationSummary`

[ pkg.go.dev | usage: schemaedge ]

Provides an OpenAPI summary for the specified operation. This should be a short summary of what the operation does.

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithOperationSummary(entrest.OperationCreate, "Create a pet."),
    }
}

`WithOperationDescription`

[ pkg.go.dev | usage: schemaedge ]

Provides an OpenAPI description for the specified operation. This should be a verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithOperationDescription(entrest.OperationCreate, "Create a pet."),
    }
}

`WithAdditionalTags`

[ pkg.go.dev | usage: schemaedge ]

Adds additional OpenAPI tags to all operations for this schema/edge. Tags can be used for logical grouping of operations by resources or any other qualifier.

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithAdditionalTags("Foo", "Bar"),
    }
}

`WithTags`

[ pkg.go.dev | usage: schemaedge ]

Sets the OpenAPI tags for all operations for this schema/edge. This will otherwise default to the schema/edge's name(s). Tags can be used for logical grouping of operations by resources or any other qualifier.

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithTags("Foo", "Bar"),
    }
}

`WithOperationID`

[ pkg.go.dev | usage: schemaedge ]

Provides an OpenAPI operation ID for the specified operation. This should be snake-cased and must be unique for the operation.

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithOperationID(entrest.OperationCreate, "createPet"),
        entrest.WithOperationID(entrest.OperationUpdate, "updatePet"),
    }
}

`WithDescription`

[ pkg.go.dev | usage: schemaedgefield ]

Sets the OpenAPI description for the specified schema/edge/field in the REST API. This will otherwise default to the schema/edge/field comment. It's recommended to use the field comment rather than setting this annotation when possible.

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithDescription("Pets are the best things ever."),
    }
}

`WithMinItemsPerPage`

[ pkg.go.dev | usage: schemaedge ]

Sets an explicit minimum number of items per page for paginated calls.

See Pagination for more information.

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithMinItemsPerPage(10),
    }
}

`WithMaxItemsPerPage`

[ pkg.go.dev | usage: schemaedge ]

Sets an explicit maximum number of items per page for paginated calls.

See Pagination for more information.

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithMaxItemsPerPage(100),
    }
}

`WithItemsPerPage`

[ pkg.go.dev | usage: schemaedge ]

Sets an explicit default number of items per page for paginated calls.

See Pagination for more information.

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithItemsPerPage(10),
    }
}

`WithEagerLoadLimit`

[ pkg.go.dev | usage: edge ]

Sets the limit for the max number of entities to eager-load for the edge. There is a global default limit for eager-loading, which can be set via the EagerLoadLimit configuration option. Defaults to1000, and the limit can be disabled by setting the value to -1.

See Eager Loading for more information.

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithEagerLoadLimit(100),
    }
}

`WithEdgeEndpoint`

[ pkg.go.dev | usage: edge ]

Sets the edge to have an endpoint. If the edge is eager-loaded, and the global config is set to disable endpoints for edges which are also eager-loaded, this will default to false. Not required to be provided unless endpoints are disabled globally and you want to specifically enable one edge to have an endpoint, or want to disable an edge from having an endpoint in general.

See Eager Loading for more information.

Example

func (Pet) Edges() []ent.Edge {
    return []ent.Edge{
        edge.To("owner", User.Type).Annotations(
            entrest.WithEdgeEndpoint(false),
        ),
    }
}

`WithEdgeUpdateBulk`

[ pkg.go.dev | usage: edge ]

Sets the edge to be bulk updated on the entities associated with the edge. This is disabled by default, which will mean that you must use the add_<field> and remove_<field> object references to associate/disassociate entities with the edge.

This is disabled by default due to the fact that this can lead to accidental disassociation of a massive number of entities, if a user doesn't happen to fully understand the implications of providing values to the bulk field, which would just be <field> (sets the non-unique edge to be set to those provided values).

See Eager Loading for more information.

Example

func (Pet) Edges() []ent.Edge {
    return []ent.Edge{
        edge.To("owner", User.Type).Annotations(
            entrest.WithEdgeUpdateBulk(true),
        ),
    }
}

`WithHandler`

[ pkg.go.dev | usage: schemaedge ]

Sets the schema/edge to have an HTTP handler generated for it. Unless a schema/edge is skipped or has the specific operation disabled, an HTTP handler/endpoint will be generated for it by default. This does not prevent the endpoint from being created within the spec, rather only prevents the handler from being mounted. The handler functions will still be generated in case you want to build upon them.

See HTTP Handler for more information.

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithHandler(true),
    }
}

`WithDeprecated`

[ pkg.go.dev | usage: schemaedgefield ]

Sets the OpenAPI deprecated flag for the specified schema/edge/field.

Example

func (Pet) Fields() []ent.Field {
    return []ent.Field{
        field.String("some_old_field").Annotations(
            entrest.WithDeprecated(true),
        ),
    }
}

`WithIncludeOperations`

[ pkg.go.dev | usage: schemaedge ]

Includes the specified operations in the REST API for the schema. If empty, all operations are generated (unless globally disabled).

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithIncludeOperations(
            entrest.OperationCreate,
            entrest.OperationDelete,
        ),
    }
}

`WithExcludeOperations`

[ pkg.go.dev | usage: schemaedge ]

Excludes the specified operations in the REST API for the schema. If empty, all operations are generated (unless globally disabled).

Example

func (Pet) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithExcludeOperations(
            entrest.OperationCreate,
            entrest.OperationDelete,
        ),
    }
}