Annotation Reference

Annotations Summary

Annotation	Usage Location	Description
WithSkip	schema edge field	Sets the schema, edge, or field to be skipped in the REST API.
WithSubentity	schema	Sets the schema to be a subentity accessible only through edges.
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	schema edge field	Sets the field to be filterable with the provided predicate(s).
WithFilterGroup	edge field	Adds the field to a group of other fields that are filtered together.
WithSchema	field	Sets the OpenAPI schema for the specified field.
WithPagination	schema edge	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	schema edge	Provides an OpenAPI summary for the specified operation.
WithOperationDescription	schema edge	Provides an OpenAPI description for the specified operation.
WithAdditionalTags	schema edge	Adds additional tags to all operations for this schema/edge.
WithTags	schema edge	Sets the tags for all operations for this schema/edge.
WithOperationID	schema edge	Provides an OpenAPI operation ID for the specified operation.
WithDescription	schema edge field	Sets the OpenAPI description for the specified schema/edge.
WithMinItemsPerPage	schema edge	Sets an explicit minimum number of items per page for paginated calls.
WithMaxItemsPerPage	schema edge	Sets an explicit maximum number of items per page for paginated calls.
WithItemsPerPage	schema edge	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	schema edge	Sets the schema/edge to be an HTTP handler generated for it.
WithDeprecated	schema edge field	Sets the OpenAPI deprecated flag for the specified schema/edge/field.
WithIncludeOperations	schema edge	Explicitly sets which operations are enabled, overriding `Config.DefaultOperations` entirely.
WithExcludeOperations	schema edge	Excludes the specified operations from `Config.DefaultOperations`.

`WithSkip`

Usage: schema edge field

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),
        ),
    }
}

`WithSubentity`

Usage: schema

Sets the schema to be a subentity that is only accessible through edges of parent entities. When set to true, no top-level endpoints are generated for this schema. The schema is still included in the OpenAPI specification as a component for response documentation, and can be eager-loaded through edges from parent schemas.

See Subentities for more information.

Example

func (PetHealth) Annotations() []ent.Annotation {
    return []ent.Annotation{
        entrest.WithSubentity(true),
    }
}

`WithReadOnly`

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`

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`

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`

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`

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`

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`

Usage: schema edge field

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 the Predicate constants in the source code for all available predicate types that can be used with entrest.WithFilter.

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`

Usage: edge field

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`

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`

Usage: schema edge

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

See Pagination for more information.

Example

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

`WithAllowClientIDs`

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`

Usage: schema edge

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`

Usage: schema edge

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`

Usage: schema edge

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`

Usage: schema edge

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`

Usage: schema edge

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`

Usage: schema edge field

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`

Usage: schema edge

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`

Usage: schema edge

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`

Usage: schema edge

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`

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 Config.EagerLoadLimit configuration option. Defaults to 1000, 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`

Usage: edge

Sets the edge to have an endpoint. If the edge is eager-loaded, and the global config Config.DisableEagerLoadedEndpoints 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`

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`

Usage: schema edge

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`

Usage: schema edge field

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`

Usage: schema edge

Explicitly sets which operations are enabled in the REST API for the schema, overriding Config.DefaultOperations entirely.

Example

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

`WithExcludeOperations`

Usage: schema edge

Excludes the specified operations from Config.DefaultOperations.

Example

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