entoas

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

• func EdgeViewName(n *gen.Type, e *gen.Edge, op Operation) (string, error)
• func GroupsForOperation(a gen.Annotations, op Operation) (serialization.Groups, error)
• func OgenSchema(f *gen.Field) (*ogen.Schema, error)
• func ViewName(n *gen.Type, op Operation) (string, error)
• func ViewNameEdge(vn string, e *gen.Edge) (string, error)
• func Views(g *gen.Graph) (map[string]*View, error)
• type Annotation
  • func CreateOperation(opts ...OperationConfigOption) Annotation
  • func DeleteOperation(opts ...OperationConfigOption) Annotation
  • func EdgeAnnotation(e *gen.Edge) (*Annotation, error)
  • func Example(v interface{}) Annotation
  • func FieldAnnotation(f *gen.Field) (*Annotation, error)
  • func Groups(gs ...string) Annotation
  • func ListOperation(opts ...OperationConfigOption) Annotation
  • func ReadOnly(readonly bool) Annotation
  • func ReadOperation(opts ...OperationConfigOption) Annotation
  • func Schema(s *ogen.Schema) Annotation
  • func SchemaAnnotation(n *gen.Type) (*Annotation, error)
  • func Skip(skip bool) Annotation
  • func UpdateOperation(opts ...OperationConfigOption) Annotation
  • func (a *Annotation) Decode(o interface{}) error
  • func (a Annotation) Merge(o schema.Annotation) schema.Annotation
  • func (Annotation) Name() string
• type Config
  • func GetConfig(cfg *gen.Config) (*Config, error)
  • func (c *Config) Decode(o interface{}) error
  • func (c Config) Name() string
• type Edge
• type Edges
  • func EdgeTree(n *gen.Type, gs serialization.Groups) (Edges, error)
  • func (es Edges) Flatten() []*gen.Edge
• type Extension
  • func NewExtension(opts ...ExtensionOption) (*Extension, error)
  • func (ex *Extension) Annotations() []entc.Annotation
  • func (ex *Extension) Hooks() []gen.Hook
• type ExtensionOption
  • func DefaultPolicy(p Policy) ExtensionOption
  • func Mutations(ms ...MutateFunc) ExtensionOption
  • func SimpleModels() ExtensionOption
  • func Spec(spec *ogen.Spec) ExtensionOption
  • func WriteTo(out io.Writer) ExtensionOption
• type MutateFunc
• type Operation
  • func EdgeOperations(e *gen.Edge) ([]Operation, error)
  • func NodeOperations(n *gen.Type) ([]Operation, error)
  • func (op Operation) Title() string
• type OperationConfig
• type OperationConfigOption
  • func OperationGroups(gs ...string) OperationConfigOption
  • func OperationPolicy(p Policy) OperationConfigOption
• type Policy
• type View

Functions

func EdgeViewName

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

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

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

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

func ViewName

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

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

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

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

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
}

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 DefaultPolicy

func DefaultPolicy(p Policy) ExtensionOption

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

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

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.