entoas

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Jul 24, 2024 License: Apache-2.0 Imports: 19 Imported by: 22

README

entoas

Generate a fully compliant, extendable OpenAPI Specification document to enable you to make use of the Swagger Tooling to generate RESTful server stubs and clients.

To generate a ready-to-use server implementation of the OpenAPI Specification generated by entoas have a look at elk.

Quick Start

Download the module:

go get -u entgo.io/contrib/entoas

Setup code generation with entc package: and register the entoas extension:

  1. Create a new Go file named ent/entc.go and paste the following content:
// +build ignore

package main

import (
	"log"

	"entgo.io/ent/entc"
	"entgo.io/ent/entc/gen"
	"entgo.io/contrib/entoas"
)

func main() {
	ex, err := entoas.NewExtension()
	if err != nil {
		log.Fatalf("creating entoas extension: %v", err)
	}
	err = entc.Generate("./schema", &gen.Config{}, entc.Extensions(ex))
	if err != nil {
		log.Fatalf("running ent codegen: %v", err)
	}
}
  1. Edit the ent/generate.go file to execute the ent/entc.go file:
package ent

//go:generate go run -mod=mod entc.go
  1. Run the code generator:
go generate ./...

Observe, that in addition to the files Ent would normally generate, another file called openapi.json was generated.

For information about configuring the generator head over to the godoc or Ent documentation.

BC

This PR introduced a slight change in the API. entoas now uses ogens OAS struct definitions to create the OAS document. This change eases Specification mutations and also enables users to use ogen to generate both Go client and server implementations for the OAS.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EdgeViewName added in v0.3.0 

func EdgeViewName(n *gen.Type, e *gen.Edge, op Operation) (string, error)

EdgeViewName returns the name for a view for a given 2nd leve operation on a gen.Edge.

func GroupsForOperation added in v0.3.0 

func GroupsForOperation(a gen.Annotations, op Operation) (serialization.Groups, error)

GroupsForOperation returns the requested groups as defined on the given Annotations for the Operation.

func OgenSchema added in v0.3.0 

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

OgenSchema returns the ogen.Schema to use for the given gen.Field.

func ViewName added in v0.3.0 

func ViewName(n *gen.Type, op Operation) (string, error)

ViewName returns the name for a view for a given operation on a gen.Type.

func ViewNameEdge added in v0.3.0 

func ViewNameEdge(vn string, e *gen.Edge) (string, error)

ViewNameEdge returns the name for a view that is an edge on the given node.

func Views 

func Views(g *gen.Graph) (map[string]*View, error)

Views returns all views that are needed to fill the OAS.

Types

type Annotation 

type Annotation struct {
	// Groups holds the serialization groups to use on this field / edge.
	Groups serialization.Groups
	// OpenAPI Specification example value for a schema field.
	Example interface{}
	// OpenAPI Specification schema to use for a schema field.
	Schema *ogen.Schema
	// Create has meta information about a creation operation.
	Create OperationConfig
	// Read has meta information about a read operation.
	Read OperationConfig
	// Update has meta information about an update operation.
	Update OperationConfig
	// Delete has meta information about a delete operation.
	Delete OperationConfig
	// List has meta information about a list operation.
	List OperationConfig
	// ReadOnly specifies that the field/edge is read only (no create/update parameter)
	ReadOnly bool
	// Skip specifies that the field will be ignored in spec.
	Skip bool
}

Annotation annotates fields and edges with metadata for spec generation.

func CreateOperation 

func CreateOperation(opts ...OperationConfigOption) Annotation

CreateOperation returns a create operation annotation.

func DeleteOperation 

func DeleteOperation(opts ...OperationConfigOption) Annotation

DeleteOperation returns a delete operation annotation.

func EdgeAnnotation 

func EdgeAnnotation(e *gen.Edge) (*Annotation, error)

EdgeAnnotation returns the Annotation on the given gen.Edge.

func Example 

func Example(v interface{}) Annotation

Example returns an example annotation.

func FieldAnnotation 

func FieldAnnotation(f *gen.Field) (*Annotation, error)

FieldAnnotation returns the Annotation on the given gen.Field.

func Groups 

func Groups(gs ...string) Annotation

Groups returns a OperationConfigOption that adds the given serialization groups to a OperationConfig.

func ListOperation 

func ListOperation(opts ...OperationConfigOption) Annotation

ListOperation returns a list operation annotation.

func ReadOnly added in v0.3.0 

func ReadOnly(readonly bool) Annotation

ReadOnly returns a read only field/edge annotation

func ReadOperation 

func ReadOperation(opts ...OperationConfigOption) Annotation

ReadOperation returns a read operation annotation.

func Schema added in v0.3.0 

func Schema(s *ogen.Schema) Annotation

Schema returns a Schema annotation.

func SchemaAnnotation 

func SchemaAnnotation(n *gen.Type) (*Annotation, error)

SchemaAnnotation returns the Annotation on the given gen.Type.

func Skip added in v0.3.1 

func Skip(skip bool) Annotation

Skip returns a skip field annotation

func UpdateOperation 

func UpdateOperation(opts ...OperationConfigOption) Annotation

UpdateOperation returns an update operation annotation.

func (*Annotation) Decode 

func (a *Annotation) Decode(o interface{}) error

Decode from ent.

func (Annotation) Merge 

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

Merge implements ent.Merger interface.

func (Annotation) Name 

func (Annotation) Name() string

Name implements schema.Annotation interface.

type Config 

type Config struct {
	// DefaultPolicy defines the default policy for endpoint generation.
	// It is used if no policy is set on a (sub-)resource.
	// Defaults to PolicyExpose.
	DefaultPolicy Policy
	// Whether or whether not to generate simple models instead of one model per endpoint.
	//
	// The OAS generator by default creates one view per endpoint. The naming strategy is the following:
	// - <S><Op> for 1st level operation Op on schema S
	// - <S><Op>_<E> for an eager loaded edge E on 1st level operation Op on schema S
	// - <S>_<E><Op> for a 2nd level operation Op on edge E on schema S
	//
	// By enabling she SimpleModels configuration the generator simply adds the defined schemas with all fields and edges.
	// Serialization groups have no effects in this mode.
	SimpleModels bool
	// When enabled, allows the built-in "id" field as part of the POST payload for entity creation, allowing the client to supply UUIDs as primary keys and for idempotency.
	// Defaults to false.
	AllowClientUUIDs bool
	// Specify the minimum amount of itemsPerPage allowed in generated pagination.
	// Defaults to 1.
	MinItemsPerPage int64
	// Specify the maximum amount of itemsPerPage allowed in generated pagination.
	// Defaults to 255.
	MaxItemsPerPage int64
}

Config provides global metadata for the generator. It is injected into the gen.Graph.

func GetConfig 

func GetConfig(cfg *gen.Config) (*Config, error)

GetConfig loads the entoas.Config from the given *gen.Config object.

func (*Config) Decode 

func (c *Config) Decode(o interface{}) error

Decode from ent.

func (Config) Name 

func (c Config) Name() string

Name implements entc.Annotation interface.

type Edge 

type Edge struct {
	*gen.Edge
	Edges Edges
}

Edge wraps a gen.Edge and denotes an edge to be returned in an operation response. It recursively defines edges to load on the gen.Type the wrapped edge is pointing at.

type Edges 

type Edges []*Edge

func EdgeTree 

func EdgeTree(n *gen.Type, gs serialization.Groups) (Edges, error)

EdgeTree returns the Edges to include on a type for the given serialization groups.

func (Edges) Flatten 

func (es Edges) Flatten() []*gen.Edge

Flatten returns a list of all gen.Edge present in the tree.

type Extension 

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

Extension implements entc.Extension interface for providing OpenAPI Specification generation.

func NewExtension 

func NewExtension(opts ...ExtensionOption) (*Extension, error)

NewExtension returns a new entoas extension with default values.

func (*Extension) Annotations 

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

Annotations of the extensions.

func (*Extension) Hooks 

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

Hooks of the Extension.

type ExtensionOption 

type ExtensionOption func(*Extension) error

ExtensionOption allows managing Extension configuration using functional arguments.

func AllowClientUUIDs added in v0.5.0 

func AllowClientUUIDs() ExtensionOption

AllowClientUUIDs enables the client supplied IDs feature.

Further information can be found at Config.AllowClientUUIDs.

func DefaultPolicy 

func DefaultPolicy(p Policy) ExtensionOption

DefaultPolicy sets the default ExclusionPolicy to use of none is given on a (sub-)schema.

func MaxItemsPerPage added in v0.3.5 

func MaxItemsPerPage(n int) ExtensionOption

MaxItemsPerPage sets the maximum value for the 'itemsPerPage' parameter in list pagination.

func MinItemsPerPage added in v0.3.5 

func MinItemsPerPage(n int) ExtensionOption

MinItemsPerPage sets the minimum value for the 'itemsPerPage' parameter in list pagination.

func Mutations 

func Mutations(ms ...MutateFunc) ExtensionOption

Mutations adds the given mutations to the spec generator.

A MutateFunc is a simple closure that can be used to edit the generated spec. It can be used to add custom endpoints or alter the spec in any other way.

func SimpleModels 

func SimpleModels() ExtensionOption

SimpleModels enables the simple model generation feature.

Further information can be found at Config.SimpleModels.

func Spec added in v0.3.0 

func Spec(spec *ogen.Spec) ExtensionOption

Spec allows to configure a pointer to an existing ogen.Spec where the code generator writes the final result to. Any configured Mutations are run before the spec is written.

func WriteTo 

func WriteTo(out io.Writer) ExtensionOption

WriteTo writes the current specs content to the given io.Writer.

type MutateFunc 

type MutateFunc func(*gen.Graph, *ogen.Spec) error

MutateFunc defines a closure to be called on a generated spec.

type Operation 

type Operation string
const (
	OpCreate Operation = "create"
	OpRead   Operation = "read"
	OpUpdate Operation = "update"
	OpDelete Operation = "delete"
	OpList   Operation = "list"
)

func EdgeOperations 

func EdgeOperations(e *gen.Edge) ([]Operation, error)

EdgeOperations returns the list of operations to expose for this edge.

func NodeOperations 

func NodeOperations(n *gen.Type) ([]Operation, error)

NodeOperations returns the list of operations to expose for this node.

func (Operation) Title 

func (op Operation) Title() string

Title returns the title cases variant of the operation.

type OperationConfig 

type OperationConfig struct {
	Policy Policy
	Groups serialization.Groups
}

OperationConfig holds meta information about a REST operation.

type OperationConfigOption 

type OperationConfigOption func(*OperationConfig)

OperationConfigOption allows managing OperationConfig using functional arguments.

func OperationGroups 

func OperationGroups(gs ...string) OperationConfigOption

OperationGroups returns a OperationConfigOption that adds the given serialization groups to a OperationConfig.

func OperationPolicy 

func OperationPolicy(p Policy) OperationConfigOption

OperationPolicy returns a OperationConfigOption that sets the Policy of a OperationConfig to the given one.

type Policy 

type Policy uint

Policy defines whether to expose and endpoint or exclude it. 

const (
	PolicyNone Policy = iota
	PolicyExclude
	PolicyExpose
)

type View 

type View struct {
	Type   *gen.Type
	Fields []*gen.Field
	Edges  []*gen.Edge
}

A View is a subset of a gen.Type. It may hold fewer Fields and Edges than the gen.Type it is derived from.

Source Files

View all Source files

Directories

Path Synopsis
internal
cycle
cycle/enttest
cycle/hook
cycle/migrate
cycle/predicate
cycle/runtime
cycle/schema
cycle/user
oastypes
oastypes/enttest
oastypes/hook
oastypes/migrate
oastypes/oastypes
oastypes/predicate
oastypes/runtime
oastypes/schema
pets
pets/category
pets/enttest
pets/hook
pets/migrate
pets/pet
pets/predicate
pets/runtime
pets/schema
pets/user
simple
simple/category
simple/enttest
simple/hook
simple/migrate
simple/pet
simple/predicate
simple/runtime
simple/schema
simple/user

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.