entrest

package module
v0.0.0-...-448ac7a Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 23, 2024 License: MIT Imports: 25 Imported by: 2

README

logo

🔗 Table of Contents

✨ Features

[!WARNING] entrest is still a work in progress. we may make breaking changes to the API without notice.

entrest is an EntGo extension for generating compliant OpenAPI specs and an HTTP handler implementation that matches that spec. It expands upon the approach used by entoas, with additional functionality, and pairs the generated specification with a fully-functional HTTP handler implementation.

  • ✨ Generates OpenAPI specs for your EntGo schema.
  • ✨ Generates a fully functional HTTP handler implementation that matches the OpenAPI spec.
  • ✨ Supports automatic pagination (where applicable).
  • ✨ Supports advanced filtering (using query parameters, AND/OR predicates, etc).
  • ✨ Supports eager-loading edges, so you don't have to make additional calls unnecessarily.
  • ✨ Supports various forms of sorting.
  • ✨ And more!

⚙ Usage

Take a look at the official documentation for guides, examples, and more.

go get -u github.com/lrstanley/entrest@latest

🙋♂ Support & Assistance

  • ❤ Please review the Code of Conduct for guidelines on ensuring everyone has the best experience interacting with the community.
  • 🙋♂ Take a look at the support document on guidelines for tips on how to ask the right questions.
  • 🐞 For all features/bugs/issues/questions/etc, head over here.

🤝 Contributing

  • ❤ Please review the Code of Conduct for guidelines on ensuring everyone has the best experience interacting with the community.
  • 📋 Please review the contributing doc for submitting issues/a guide on submitting pull requests and helping out.
  • 🗝 For anything security related, please review this repositories security policy.

⚖ License

MIT License

Copyright (c) 2024 Liam Stanley <liam@liam.sh>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Also located here

Documentation

Index

Constants

View Source 
const OpenAPIVersion = "3.0.3"

Variables

View Source 
var (
	// Add all casing and word-massaging functions here so others can use them if they
	// want to customize the naming of their spec/endpoints/etc.
	Pluralize   = memoize(inflect.Pluralize) // nolint: errcheck,unused
	KebabCase   = memoize(strcase.KebabCase)
	Singularize = memoize(gen.Funcs["singular"].(func(string) string)) // nolint: errcheck,unused
	PascalCase  = memoize(gen.Funcs["pascal"].(func(string) string))   // nolint: errcheck,unused
	CamelCase   = memoize(gen.Funcs["camel"].(func(string) string))    // nolint: errcheck,unused
	SnakeCase   = memoize(gen.Funcs["snake"].(func(string) string))    // nolint: errcheck,unused
)
View Source 
var (
	// RateLimitHeaders are standardized rate limit response headers.
	RateLimitHeaders = ResponseHeaders{
		"X-Ratelimit-Limit": {
			Description: "The maximum number of requests that the consumer is permitted to make in a given period.",
			Required:    true,
			Schema:      &ogen.Schema{Type: "integer"},
		},
		"X-Ratelimit-Remaining": {
			Description: "The number of requests remaining in the current rate limit window.",
			Required:    true,
			Schema:      &ogen.Schema{Type: "integer"},
		},
		"X-Ratelimit-Reset": {
			Description: "The time at which the current rate limit window resets in UTC epoch seconds.",
			Required:    true,
			Schema:      &ogen.Schema{Type: "integer"},
		},
	}

	// RequestIDHeader is a standardized request ID request header.
	RequestIDHeader = RequestHeaders{
		"X-Request-Id": {
			Description: "A unique identifier for the request.",
			Required:    false,
			Schema:      &ogen.Schema{Type: "string"},
		},
	}

	// DefaultErrorResponses are the default error responses for the HTTP status codes,
	// which includes 400, 401, 403, 404, 409, 429, and 500.
	DefaultErrorResponses = ErrorResponses{
		http.StatusBadRequest:          ErrorResponseObject(http.StatusBadRequest),
		http.StatusUnauthorized:        ErrorResponseObject(http.StatusUnauthorized),
		http.StatusForbidden:           ErrorResponseObject(http.StatusForbidden),
		http.StatusNotFound:            ErrorResponseObject(http.StatusNotFound),
		http.StatusConflict:            ErrorResponseObject(http.StatusConflict),
		http.StatusTooManyRequests:     ErrorResponseObject(http.StatusTooManyRequests),
		http.StatusInternalServerError: ErrorResponseObject(http.StatusInternalServerError),
	}
)
View Source 
var AllOperations = []Operation{OperationCreate, OperationRead, OperationUpdate, OperationDelete, OperationList}

AllOperations holds a list of all supported operations.

View Source 
var AllSupportedHTTPHandlers = []HTTPHandler{
	HandlerNone,
	HandlerStdlib,
	HandlerChi,
}

AllSupportedHTTPHandlers is a list of all supported HTTP handlers.

View Source 
var SchemaObjectAny = &ogen.Schema{
	Type: "object",
	AdditionalProperties: &ogen.AdditionalProperties{
		Bool: ptr(true),
	},
}

SchemaObjectAny can be used to define an object which may contain any properties.

Functions

func ErrorResponseObject 

func ErrorResponseObject(code int) *ogen.Schema

ErrorResponseObject returns a default error schema for the provided HTTP status code.

func FuncMaps 

func FuncMaps() template.FuncMap

FuncMaps export FuncMaps to use custom templates.

func GetOperationIDName 

func GetOperationIDName(op Operation, t *gen.Type, e *gen.Edge) string

GetOperationIDName returns the operation ID for the given operation, type, and optional edge, or the OperationID provided by the annotation if it exists.

func GetPathName 

func GetPathName(op Operation, t *gen.Type, e *gen.Edge, useUniqueID bool) string

GetPathName returns the path name for the given operation, type, and optional edge, or the OperationID provided by the annotation if it exists. useUniqueID determines if the ID path parameter should be "{id}" or "{type|camel}ID".

func GetSchemaField 

func GetSchemaField(f *gen.Field) (*ogen.Schema, error)

GetSchemaField generates a schema for the given field, if its supported. If the field you have provided is not supported, use the WithSchema annotation on the field to provide a custom schema (primarily beneficial for JSON fields).

func GetSchemaType 

func GetSchemaType(t *gen.Type, op Operation, edge *gen.Edge) map[string]*ogen.Schema

GetSchemaType returns a map of ogen.Schemas for the given gen.Type. Multiple may be returned if the type has multiple schemas (e.g. a list of entities, or an entity which has edges). Note that depending on the operation, this schema may be for the request or response, or both. Edge should be provided only if the type is from an edge schema.

func GetSortableFields 

func GetSortableFields(t *gen.Type, edge *gen.Edge) (sortable []string)

GetSortableFields returnsd a list of sortable fields for the given type. It recurses through edges to find sortable fields as well.

func GetSpecEdge 

func GetSpecEdge(t *gen.Type, e *gen.Edge, op Operation) (*ogen.Spec, error)

GetSpecEdge generates an independent spec for the given edge, which should encapsulate all schemas, parameters, components and paths for the provided edge that can then be merged into another spec.

func GetSpecType 

func GetSpecType(t *gen.Type, op Operation) (*ogen.Spec, error)

GetSpecType generates an independent spec for the given type, which should encapsulate all schemas, parameters, components and paths for the provided type that can then be merged into another spec.

func MergeSpec 

func MergeSpec(orig *ogen.Spec, toMerge ...*ogen.Spec) error

MergeSpec merges multiple ogen.Spec into a single ogen.Spec. This does not cover all possible fields, and is not a full merge. It's a simple merge at the core-component level, for things like servers, paths, components, tags, etc.

func MergeSpecOverlap 

func MergeSpecOverlap(orig *ogen.Spec, toMerge ...*ogen.Spec) error

MergeSpecOverlap merges multiple ogen.Spec into a single ogen.Spec, allowing for overlapping fields. This does not cover all possible fields, and is not a full merge. It's a simple merge at the core-component level, for things like servers, paths, components, tags, etc.

func PatchOperations 

func PatchOperations(pathItem *ogen.PathItem, cb func(method string, op *ogen.Operation) *ogen.Operation) *ogen.PathItem

PatchOperations applies a callback to each operation in a path inside of the OpenAPI spec.

func PatchPathItem 

func PatchPathItem(pathItem *ogen.PathItem, cb func(resp *ogen.Response) *ogen.Response) *ogen.PathItem

PatchPathItem applies a callback to each response in a path inside of the OpenAPI spec.

func ToEnum 

func ToEnum[T any](values []T) ([]json.RawMessage, error)

ToEnum returns a slice of json.RawMessage from a slice of T. This is useful when using the WithSchema annotation.

func ValidateAnnotations 

func ValidateAnnotations(nodes ...*gen.Type) error

ValidateAnnotations ensures that all annotations on the given graph are correctly attached to the right types (e.g. a field-only annotation on a schema or edge type).

Types

type Annotation 

type Annotation struct {
	AdditionalTags       []string             `json:",omitempty" ent:"schema,edge"`
	Tags                 []string             `json:",omitempty" ent:"schema,edge"`
	OperationSummary     map[Operation]string `json:",omitempty" ent:"schema,edge"`
	OperationDescription map[Operation]string `json:",omitempty" ent:"schema,edge"`
	OperationID          map[Operation]string `json:",omitempty" ent:"schema,edge"`
	Description          string               `json:",omitempty" ent:"schema,edge,field"`
	Example              any                  `json:",omitempty" ent:"field"`
	Deprecated           bool                 `json:",omitempty" ent:"schema,edge,field"`
	Schema               *ogen.Schema         `json:",omitempty" ent:"field"`
	ReadOnly             bool                 `json:",omitempty" ent:"field"`

	Pagination      *bool       `json:",omitempty" ent:"schema,edge"`
	MinItemsPerPage int         `json:",omitempty" ent:"schema,edge"`
	MaxItemsPerPage int         `json:",omitempty" ent:"schema,edge"`
	ItemsPerPage    int         `json:",omitempty" ent:"schema,edge"`
	EagerLoad       *bool       `json:",omitempty" ent:"edge"`
	EagerLoadLimit  *int        `json:",omitempty" ent:"edge"`
	EdgeEndpoint    *bool       `json:",omitempty" ent:"edge"`
	EdgeUpdateBulk  bool        `json:",omitempty" ent:"edge"`
	Filter          Predicate   `json:",omitempty" ent:"schema,edge,field"`
	FilterGroup     string      `json:",omitempty" ent:"edge,field"`
	DisableHandler  bool        `json:",omitempty" ent:"schema,edge"`
	Sortable        bool        `json:",omitempty" ent:"field"`
	DefaultSort     *string     `json:",omitempty" ent:"schema"`
	DefaultOrder    *SortOrder  `json:",omitempty" ent:"schema"`
	Skip            bool        `json:",omitempty" ent:"schema,edge,field"`
	Operations      []Operation `json:",omitempty" ent:"schema,edge"`
}

Annotation adds configuration options for specific layers of the Ent graph.

func GetAnnotation 

func GetAnnotation(v any) *Annotation

GetAnnotation returns the annotation on the given graph item.

func WithAdditionalTags 

func WithAdditionalTags(v ...string) Annotation

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

func WithDefaultOrder 

func WithDefaultOrder(v SortOrder) Annotation

WithDefaultOrder 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.

func WithDefaultSort 

func WithDefaultSort(field string) Annotation

WithDefaultSort 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.

func WithDeprecated 

func WithDeprecated(v bool) Annotation

WithDeprecated sets the field to be deprecated in the REST API.

func WithDescription 

func WithDescription(v string) Annotation

WithDescription sets the description for the schema/edge/field in the REST API. This will otherwise default to the schema/edge/field's description according to Ent (e.g. the comment). It's recommended to use the field comment rather than setting this annotation when possible.

func WithEagerLoad 

func WithEagerLoad(v bool) Annotation

WithEagerLoad 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).

func WithEagerLoadLimit 

func WithEagerLoadLimit(v int) Annotation

WithEagerLoadLimit 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 [Config.EagerLoadLimit]. Defaults to 1000, and the limit can be disabled by setting the value to -1.

func WithEdgeEndpoint 

func WithEdgeEndpoint(v bool) Annotation

WithEdgeEndpoint 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.

func WithEdgeUpdateBulk 

func WithEdgeUpdateBulk(v bool) Annotation

WithEdgeUpdateBulk allows 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).

func WithExample 

func WithExample(v any) Annotation

WithExample sets the OpenAPI Specification example value for a 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.

func WithExcludeOperations 

func WithExcludeOperations(v ...Operation) Annotation

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

func WithFilter 

func WithFilter(v Predicate) Annotation

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

Example: 

entrest.WithFilter(entrest.FilterGroupArray | entrest.FilterGroupLength) // Bundle using groups.
entrest.WithFilter(entrest.FilterEQ | entrest.FilterNEQ) // Or use individual predicates.

func WithFilterGroup 

func WithFilterGroup(name string) Annotation

WithFilterGroup 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. This allows slightly more advanced logical operations, like the following:

  • and(type.eq==FOO, or(field1.ihas==bar, field2.ihas==bar, field3.ihas==bar))

You can 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.

func WithHandler 

func WithHandler(v bool) Annotation

WithHandler 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.

func WithIncludeOperations 

func WithIncludeOperations(v ...Operation) Annotation

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

func WithItemsPerPage 

func WithItemsPerPage(v int) Annotation

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

func WithMaxItemsPerPage 

func WithMaxItemsPerPage(v int) Annotation

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

func WithMinItemsPerPage 

func WithMinItemsPerPage(v int) Annotation

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

func WithOperationDescription 

func WithOperationDescription(op Operation, v string) Annotation

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

func WithOperationID 

func WithOperationID(op Operation, v string) Annotation

WithOperationID provides an operation ID for the specified operation. This should be snake-cased and MUST BE UNIQUE for the operation.

func WithOperationSummary 

func WithOperationSummary(op Operation, v string) Annotation

WithOperationSummary provides a summary for the specified operation. This should be a short summary of what the operation does.

func WithPagination 

func WithPagination(v bool) Annotation

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

func WithReadOnly 

func WithReadOnly(v bool) Annotation

WithReadOnly 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.

func WithSchema 

func WithSchema(v *ogen.Schema) Annotation

WithSchema 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 SchemaObjectAny for an object with any properties (effectively "any").

func WithSkip 

func WithSkip(v bool) Annotation

WithSkip 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).

func WithSortable 

func WithSortable(v bool) Annotation

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

func WithTags 

func WithTags(v ...string) Annotation

Sets the 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.

func (*Annotation) Decode 

func (a *Annotation) Decode(o any) error

func (*Annotation) GetDefaultOrder 

func (a *Annotation) GetDefaultOrder() SortOrder

GetDefaultOrder returns the default sorting order for the schema in the REST API, defaulting to ascending if not specified.

func (*Annotation) GetDefaultSort 

func (a *Annotation) GetDefaultSort(hasID bool) string

GetDefaultSort returns the default sort field for the schema in the REST API. If one was not previously specified, but the type has an ID field, it will default to "id".

func (*Annotation) GetEagerLoad 

func (a *Annotation) GetEagerLoad(config *Config) bool

GetEagerLoad returns if the edge should be eager-loaded (or defaults from [Config.DefaultEagerLoad]).

func (*Annotation) GetEagerLoadLimit 

func (a *Annotation) GetEagerLoadLimit(config *Config) int

GetEagerLoadLimit returns the limit for the max number of entities to eager-load for the edge (or defaults from [Config.EagerLoadLimit]).

func (*Annotation) GetEdgeEndpoint 

func (a *Annotation) GetEdgeEndpoint(config *Config) bool

GetEdgeEndpoint returns if the edge should have an endpoint (or defaults from [Config.DisableEagerLoadedEndpoints]).

func (*Annotation) GetItemsPerPage 

func (a *Annotation) GetItemsPerPage(config *Config) int

GetItemsPerPage returns the number of items per page for paginated calls (or defaults from [Config.ItemsPerPage]).

func (*Annotation) GetMaxItemsPerPage 

func (a *Annotation) GetMaxItemsPerPage(config *Config) int

GetMaxItemsPerPage returns the maximum number of items per page for paginated calls (or defaults from [Config.MaxItemsPerPage]).

func (*Annotation) GetMinItemsPerPage 

func (a *Annotation) GetMinItemsPerPage(config *Config) int

GetMinItemsPerPage returns the minimum number of items per page for paginated calls (or defaults from [Config.MinItemsPerPage]).

func (*Annotation) GetOperationDescription 

func (a *Annotation) GetOperationDescription(op Operation) string

GetOperationDescription returns the description for the provided operation or an empty string if not configured.

func (*Annotation) GetOperationID 

func (a *Annotation) GetOperationID(op Operation) string

GetOperationID returns the operation ID for the provided operation or an empty string if not configured.

func (*Annotation) GetOperationSummary 

func (a *Annotation) GetOperationSummary(op Operation) string

GetOperationSummary returns the summary for the provided operation or an empty string if not configured.

func (*Annotation) GetOperations 

func (a *Annotation) GetOperations(config *Config) []Operation

GetOperations returns the operations annotation (or defaults from [Config.DefaultOperations]).

func (*Annotation) GetPagination 

func (a *Annotation) GetPagination(config *Config, edge *gen.Edge) bool

GetPagination returns the pagination annotation (or defaults from [Config.DisablePagination] and [Config.DefaultEagerLoad] depending on the type/edge/etc).

func (*Annotation) GetSkip 

func (a *Annotation) GetSkip(config *Config) bool

func (*Annotation) HasOperation 

func (a *Annotation) HasOperation(config *Config, op Operation) bool

HasOperation returns if the operation is allowed on the given annotation.

func (Annotation) Merge 

func (a Annotation) Merge(o schema.Annotation) schema.Annotation

Merge merges the given annotation into the current annotation.

func (Annotation) Name 

func (Annotation) Name() string

type Config 

type Config struct {

	// Spec is an optional default spec to merge all generated endpoints/schemas/etc
	// into, which will allow you to specify API info, servers, security schemes, etc.
	Spec *ogen.Spec

	// SpecFromPath is similar to [Config.Spec], but instead of providing a spec directly,
	// it will read the spec (json) from the provided path. If you have a combination
	// of auto-generated endpoints from this extension, plus a bunch of your own endpoints,
	// this can make it very easy to layer each of the specs on top of each other, as it
	// can be a bit tedious to use [Config.Spec] directly.
	SpecFromPath string

	// DisablePagination disables pagination support for all schemas by default.
	// It scan still be enabled on a per-schema basis with annotations.
	DisablePagination bool

	// MinItemsPerPage controls the default minimum number of items per page, for
	// paginated calls. This can be overridden on a per-schema basis with annotations.
	MinItemsPerPage int

	// MaxItemsPerPage controls the default maximum number of items per page, for
	// paginated calls. This can be overridden on a per-schema basis with annotations.
	MaxItemsPerPage int

	// ItemsPerPage controls the default number of items per page, for paginated calls.
	// This can be overridden on a per-schema basis with annotations.
	ItemsPerPage int

	// DefaultEagerLoad enables eager loading of all edges by default. This can be
	// overridden on a per-edge basis with annotations. If edges load a lot of data
	// or are expensive, this can be a performance hit and isn't recommended.
	DefaultEagerLoad bool

	// DisableEagerLoadNonPagedOpt disables the optimization which automatically disables
	// the pagination for edge endpoints where the edge was also eager-loaded. The idea for
	// the optimization is that if the edge is also eager-loaded, then the amount of data
	// isn't large enough to justify the additional overhead of pagination, so we can
	// disable it.
	DisableEagerLoadNonPagedOpt bool

	// DisableEagerLoadedEndpoints disables the generation of dedicated endpoints for
	// edges which are also eager-loaded. This can be useful to reduce the number of
	// endpoints generated, but does mean that callers would have to always call the
	// entity which eager loads the edge, rather than only fetching the edge itself.
	// This can be overridden on a per-edge basis with annotations.
	//
	// Example: Given a schema with users and pets, and an edge on pets called "owner",
	// pointing to user, if you configure owner to be eager-loaded (so any time you query
	// a pet, you also get the owner), setting this to true will then disable the
	// /pets/{id}/owner endpoint (idea being that you could just call /pets/{id} and
	// get the owner from that response).
	DisableEagerLoadedEndpoints bool

	// EagerLoadLimit controls the default maximum number of results that can be
	// eager-loaded for a given edge. The default, when not specified, is 1000. The limit
	// can be disabled by setting the value to -1. The intent of this option is to
	// provide a safe default cap on the number of eager-loaded results, to prevent
	// potential abuse, denial-of-service/resource-exhaustion, etc.
	//
	// This can be overridden on a per-edge basis with annotations.
	EagerLoadLimit int

	// AddEdgesToTags enables the addition of edge fields to the "tags" field in the
	// OpenAPI spec. This is helpful to see if querying a specific entity also returns
	// the thing you're looking for, though can be very noisy for large schemas. Note
	// that edge endpoints (e.g. /users/{id}/pets) will still have both "User" and "Pet"
	// in the tags, this only affects eager-loaded edges.
	AddEdgesToTags bool

	// DefaultFilterID enables the default filter for ID fields, which applies
	// [FilterGroupEqualExact] and [FilterGroupArray] to the ID field. This is helpful
	// if you don't explicitly declare your "id" field in your schema (as it is handled
	// by default by ent).
	DefaultFilterID bool

	// DefaultOperations is a list of operations to generate by default. If nil,
	// all operations will be generated by default (unless excluded with annotations).
	DefaultOperations []Operation

	// GlobalRequestHeaders are headers to add to every request, which can be optional
	// (e.g. X-Request-Id or X-Correlation-ID), or required (e.g. API version). Note
	// that these should not include anything related to authentication -- use the
	// security schemes instead via [Config.Spec].
	GlobalRequestHeaders RequestHeaders

	// GlobalResponseHeaders are headers to add to every response, recommended for headers
	// like X-Ratelimit-Limit, X-Ratelimit-Remaining, X-Ratelimit-Reset, etc.
	GlobalResponseHeaders ResponseHeaders

	// GlobalErrorResponses are status code -> response mappings for errors, which are
	// added to all path operations. Note that some status codes are excluded on specific
	// operations (e.g. 404 on list, 409 on non-create/update, etc). If not specified,
	// a default set of responses will be generated which can be used with entrest's
	// built-in auto-generated HTTP handlers (see below). Defaults to [DefaultErrorResponses].
	GlobalErrorResponses ErrorResponses

	// Handler enables the generation of HTTP handlers for the specified server/routing
	// library. If this is disabled, no Go code will be generated, and only the OpenAPI
	// spec will be generated.
	Handler HTTPHandler

	// StrictMutate if set to true, will cause a 400 "Bad Request" response if an unknown
	// field is provided to the update/create/etc functions. This is useful for ensuring
	// that all fields are provided, and that the client is not attempting to provide
	// fields that are not defined in the schema.
	StrictMutate bool

	// ListNotFound if set to true, will cause a 404 "Not Found" response if a list endpoint
	// (with any filtering as part of the request) returns no results. This is technically
	// "more correct" according to the RFC, but some prefer to return a 200 "OK". In either
	// case, the body of the response would still be the typical pagination or list object,
	// with the "content" field being an empty array.
	ListNotFound bool

	// DisableSpecHandler disables the generation of an OpenAPI spec handler (e.g.
	// /openapi.json). Disabling this will also disable embedding the spec into the
	// binary/rest generated library.
	DisableSpecHandler bool

	// AllowClientIDs, when enabled, allows the built-in "id" field as part of a "Create"
	// payload for entity creation, allowing the client to supply UUIDs as primary keys
	// and for idempotency.
	AllowClientUUIDs bool

	// DisablePatchJSONTag disables a ent generation hook that patches the JSON tag of all
	// fields in the schema, removing the usage of omitempty. This helps ensure that fields
	// that have default values and/or aren't required, still get returned in JSON response
	// bodies. Skips over fields which are json-excluded (e.g. sensitive data).
	DisablePatchJSONTag bool

	// WithTesting enables the generation of a resttest package, which contains a
	// set of helpers for testing the generated REST API.
	WithTesting bool

	// PreHook is a hook that runs before the spec is generated. This is useful for
	// things like adding global security schemes, or adding global request headers,
	// if you're unable to provide the [Config.Spec] field for some reason.
	PreGenerateHook func(g *gen.Graph, spec *ogen.Spec) error `json:"-"`

	// PostHook is a hook that runs after the spec is generated, but before we run global
	// writers (headers, error codes, etc) as well as before we write the spec to disk.
	// Recommended for adding additional paths so they can also receive the global headers,
	// error codes, etc.
	PostGenerateHook func(g *gen.Graph, spec *ogen.Spec) error `json:"-"`

	// PreWriteHook is similar to PostGenerateHook, except it is run directly before
	// writing to disk, after the entire spec has been resolved.
	PreWriteHook func(spec *ogen.Spec) error `json:"-"`

	// Writer is an optional writer to write the spec to. If not provided, the spec
	// will be written to the filesystem under "<ent>/rest/openapi.json".
	Writer io.Writer `json:"-"`

	// Templates a universal template that can be used to add or replace an existing template.
	Templates []*gen.Template `json:"-"`
	// contains filtered or unexported fields
}

Config holds the main configuration for this extension.

func GetConfig 

func GetConfig(gc *gen.Config) *Config

GetConfig returns the rest config for the given graph. If the graph does not contain the config (extension was not loaded), this will panic.

func (*Config) Decode 

func (c *Config) Decode(o any) error

func (Config) Name 

func (c Config) Name() string

func (*Config) Validate 

func (c *Config) Validate() error

type ErrorResponses 

type ErrorResponses map[int]*ogen.Schema

func (ErrorResponses) Append 

func (r ErrorResponses) Append(toMerge ...ErrorResponses) ErrorResponses

Append merges the provided error responses into the current error responses, returning a new error responses map.

type Extension 

type Extension struct {
	entc.DefaultExtension
	// contains filtered or unexported fields
}

func NewExtension 

func NewExtension(config *Config) (*Extension, error)

func (*Extension) Annotations 

func (e *Extension) Annotations() []entc.Annotation

func (*Extension) Generate 

func (e *Extension) Generate(g *gen.Graph) (*ogen.Spec, error)

func (*Extension) Hooks 

func (e *Extension) Hooks() []gen.Hook

func (*Extension) Templates 

func (e *Extension) Templates() []*gen.Template

type FilterGroup 

type FilterGroup struct {
	Name       string
	Type       *gen.Type
	FieldType  *field.TypeInfo
	Operations []gen.Op
	FieldPairs []*FilterGroupFieldPair
	Schema     *ogen.Schema
}

func GetFilterGroups 

func GetFilterGroups(t *gen.Type, edge *gen.Edge) []*FilterGroup

func (*FilterGroup) ComponentName 

func (g *FilterGroup) ComponentName(op gen.Op) string

ComponentName returns the name/component alias for the parameter.

func (*FilterGroup) Description 

func (g *FilterGroup) Description(op gen.Op) string

func (*FilterGroup) Parameter 

func (g *FilterGroup) Parameter(op gen.Op) *ogen.Parameter

Parameter returns the parameter for the filter group.

func (*FilterGroup) ParameterName 

func (g *FilterGroup) ParameterName(op gen.Op) string

ParameterName returns the raw query parameter name for the filter group.

func (*FilterGroup) PredicateBuilder 

func (g *FilterGroup) PredicateBuilder(structName string, op gen.Op) string

func (*FilterGroup) StructTag 

func (g *FilterGroup) StructTag(op gen.Op) string

StructTag returns the struct tag for the filter group, which uses json and github.com/go-playground/validator based tags by default.

func (*FilterGroup) TypeString 

func (g *FilterGroup) TypeString(op gen.Op) string

TypeString returns the struct field type for the filter group.

type FilterGroupFieldPair 

type FilterGroupFieldPair struct {
	Type  *gen.Type
	Edge  *gen.Edge
	Field *gen.Field
}

type FilterableFieldOp 

type FilterableFieldOp struct {
	Type      *gen.Type
	Edge      *gen.Edge  // Edge may be nil.
	Field     *gen.Field // Field may be nil (if so, assume we want a parameter to check for the edges existence).
	Operation gen.Op     // The associated operation.
	// contains filtered or unexported fields
}

FilterableFieldOp represents a filterable field, that filters based on a specific operation (e.g. eq, neq, gt, lt, etc).

func GetFilterableFields 

func GetFilterableFields(t *gen.Type, edge *gen.Edge) (filters []*FilterableFieldOp)

GetFilterableFields returns a list of filterable fields for the given type, where the key is the component name, and the value is the parameter which includes the name, description and schema for the parameter.

func (*FilterableFieldOp) ComponentName 

func (f *FilterableFieldOp) ComponentName() string

ComponentName returns the name/component alias for the parameter.

func (*FilterableFieldOp) Description 

func (f *FilterableFieldOp) Description() string

Description returns a description for the filterable field.

func (*FilterableFieldOp) Parameter 

func (f *FilterableFieldOp) Parameter() *ogen.Parameter

Parameter returns the parameter for the filterable field.

func (*FilterableFieldOp) ParameterName 

func (f *FilterableFieldOp) ParameterName() string

ParameterName returns the raw query parameter name for the filterable field.

func (*FilterableFieldOp) PredicateBuilder 

func (f *FilterableFieldOp) PredicateBuilder(structName string) string

func (*FilterableFieldOp) StructTag 

func (f *FilterableFieldOp) StructTag() string

StructTag returns the struct tag for the filterable field, which uses json and github.com/go-playground/validator based tags by default.

func (*FilterableFieldOp) TypeString 

func (f *FilterableFieldOp) TypeString() string

TypeString returns the struct field type for the filterable field.

type HTTPHandler 

type HTTPHandler string

HTTPHandler represents the HTTP handler to use for the HTTP server implementation. 

const (
	// HandlerNone disables all code generation for the HTTP server implementation.
	HandlerNone HTTPHandler = ""
	// HandlerStdlib uses a net/http servemux, along with the Go 1.22 advanced
	// path matching functionality to map methods and URL parameters (e.g. {id}).
	// Technically, this can be used with many other stdlib-compatible routers,
	// as long as they support [http.Request.PathValue] for path parameters.
	HandlerStdlib HTTPHandler = "stdlib"
	// HandlerChi uses the chi router, mounting each endpoint individually using
	// the provided router. Note that you must use at least chi v5.0.12 or newer,
	// which supports populating the requests path values, and accessing them via
	// [http.Request.PathValue].
	HandlerChi HTTPHandler = "chi"
)

type Operation 

type Operation string

Operation represents the CRUD operation(s). 

const (
	// OperationCreate represents the create operation (method: POST).
	OperationCreate Operation = "create"
	// OperationRead represents the read operation (method: GET).
	OperationRead Operation = "read"
	// OperationUpdate represents the update operation (method: PATCH).
	OperationUpdate Operation = "update"
	// OperationDelete represents the delete operation (method: DELETE).
	OperationDelete Operation = "delete"
	// OperationList represents the list operation (method: GET).
	OperationList Operation = "list"
)

type Predicate 

type Predicate int

Predicate represents a filtering predicate provided by ent. 

const (
	// FilterEdge is a special filter which is applied to the edge itself, indicating
	// that all of the edges fields should also be included in filtering options.
	FilterEdge Predicate = 1 << iota

	FilterEQ           // =
	FilterNEQ          // <>
	FilterGT           // >
	FilterGTE          // >=
	FilterLT           // <
	FilterLTE          // <=
	FilterIsNil        // IS NULL / has
	FilterIn           // within
	FilterNotIn        // without
	FilterEqualFold    // equals case-insensitive
	FilterContains     // containing
	FilterContainsFold // containing case-insensitive
	FilterHasPrefix    // startingWith
	FilterHasSuffix    // endingWith

	// FilterGroupEqualExact includes: eq, neq, equal fold, is nil.
	FilterGroupEqualExact = FilterEQ | FilterNEQ | FilterEqualFold | FilterGroupNil
	// FilterGroupEqual includes: eq, neq, equal fold, contains, contains case, prefix, suffix, nil.
	FilterGroupEqual = FilterGroupEqualExact | FilterGroupContains | FilterHasPrefix | FilterHasSuffix
	// FilterGroupContains includes: contains, contains case, is nil.
	FilterGroupContains = FilterContains | FilterContainsFold | FilterGroupNil
	// FilterGroupNil includes: is nil.
	FilterGroupNil = FilterIsNil
	// FilterGroupLength includes: gt, lt (often gte/lte isn't really needed).
	FilterGroupLength = FilterGT | FilterLT
	// FilterGroupArray includes: in, not in.
	FilterGroupArray = FilterIn | FilterNotIn
)

Mirrored from entgo.io/ent/entc/gen with special groupings and support for bitwise operations.

func (Predicate) Add 

func (p Predicate) Add(v Predicate) Predicate

Add adds the provided predicate to the current predicate.

func (Predicate) Explode 

func (p Predicate) Explode() (ops []gen.Op)

Explode returns all individual predicates as []gen.Op.

func (Predicate) Has 

func (p Predicate) Has(v Predicate) bool

Has returns if the predicate has the provided predicate.

func (Predicate) Remove 

func (p Predicate) Remove(v Predicate) Predicate

Remove removes the provided predicate from the current predicate.

func (Predicate) String 

func (p Predicate) String() string

String returns the gen.Op string representation of a predicate.

type RequestHeaders 

type RequestHeaders map[string]*ogen.Parameter

func (RequestHeaders) Append 

func (r RequestHeaders) Append(toMerge ...RequestHeaders) RequestHeaders

Append merges the provided request headers into the current request headers, returning a new request headers map.

type ResponseHeaders 

type ResponseHeaders map[string]*ogen.Header

func (ResponseHeaders) Append 

func (r ResponseHeaders) Append(toMerge ...ResponseHeaders) ResponseHeaders

Append merges the provided response headers into the current response headers, returning a new response headers map.

type SortOrder 

type SortOrder string

SortOrder represents the sorting order. 

const (
	// OrderAsc represents an ascending order.
	OrderAsc SortOrder = "asc"
	// OrderDesc represents a descending order.
	OrderDesc SortOrder = "desc"
)

Source Files

View all Source files

Directories

Path Synopsis
_examples module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.