openapi

Documentation

Overview

Package openapi provides functionality for mapping CUE to and from OpenAPI v3.0.0.

It currently handles OpenAPI Schema components only.

See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#schema-object

Index

• func Extract(data cue.InstanceOrValue, c *Config) (*ast.File, error)
• func Gen(inst cue.InstanceOrValue, c *Config) ([]byte, error)
• func Generate(inst cue.InstanceOrValue, c *Config) (*ast.File, error)
• type Config
• type Generator
  • func (g *Generator) All(inst cue.InstanceOrValue) (*OrderedMap, error)
  • func (g *Generator) Schemas(inst cue.InstanceOrValue) (*OrderedMap, error)
• type KeyValue
• type OrderedMap
  • func (m *OrderedMap) MarshalJSON() (b []byte, err error)
  • func (m *OrderedMap) Pairs() []KeyValue
  • func (m *OrderedMap) Set(key string, x interface{})
  • func (m *OrderedMap) SetAll(kvs []KeyValue)

Functions

func Extract

func Extract(data cue.InstanceOrValue, c *Config) (*ast.File, error)

Extract converts OpenAPI definitions to an equivalent CUE representation.

It currently only converts entries in #/components/schema and extracts some meta data.

func Gen

func Gen(inst cue.InstanceOrValue, c *Config) ([]byte, error)

Gen generates the set OpenAPI schema for all top-level types of the given instance.

func Generate

func Generate(inst cue.InstanceOrValue, c *Config) (*ast.File, error)

Generate generates the set of OpenAPI schema for all top-level types of the given instance.

Note: only a limited number of top-level types are supported so far.

Types

type Config

type Config struct {
	// PkgName defines to package name for a generated CUE package.
	PkgName string

	// Info specifies the info section of the OpenAPI document. To be a valid
	// OpenAPI document, it must include at least the title and version fields.
	// Info may be a *ast.StructLit or any type that marshals to JSON.
	Info interface{}

	// ReferenceFunc allows users to specify an alternative representation
	// for references. An empty string tells the generator to expand the type
	// in place and, if applicable, not generate a schema for that entity.
	//
	// If this field is non-nil and a cue.Value is passed as the InstanceOrValue,
	// there will be a panic.
	//
	// Deprecated: use NameFunc instead.
	ReferenceFunc func(inst *cue.Instance, path []string) string

	// NameFunc allows users to specify an alternative representation
	// for references. It is called with the value passed to the top level
	// method or function and the path to the entity being generated.
	// If it returns an empty string the generator will  expand the type
	// in place and, if applicable, not generate a schema for that entity.
	//
	// Note: this only returns the final element of the /-separated
	// reference.
	NameFunc func(val cue.Value, path cue.Path) string

	// DescriptionFunc allows rewriting a description associated with a certain
	// field. A typical implementation compiles the description from the
	// comments obtains from the Doc method. No description field is added if
	// the empty string is returned.
	DescriptionFunc func(v cue.Value) string

	// SelfContained causes all non-expanded external references to be included
	// in this document.
	SelfContained bool

	// OpenAPI version to use. Supported as of v3.0.0.
	Version string

	// FieldFilter defines a regular expression of all fields to omit from the
	// output. It is only allowed to filter fields that add additional
	// constraints. Fields that indicate basic types cannot be removed. It is
	// an error for such fields to be excluded by this filter.
	// Fields are qualified by their Object type. For instance, the
	// minimum field of the schema object is qualified as Schema/minimum.
	FieldFilter string

	// ExpandReferences replaces references with actual objects when generating
	// OpenAPI Schema. It is an error for an CUE value to refer to itself
	// if this option is used.
	ExpandReferences bool
}

A Config defines options for converting CUE to and from OpenAPI.

type Generator

type Generator = Config

func (*Generator) All

func (g *Generator) All(inst cue.InstanceOrValue) (*OrderedMap, error)

All generates an OpenAPI definition from the given instance.

Note: only a limited number of top-level types are supported so far. Deprecated: use Generate

func (*Generator) Schemas

func (g *Generator) Schemas(inst cue.InstanceOrValue) (*OrderedMap, error)

Schemas extracts component/schemas from the CUE top-level types.

type KeyValue

type KeyValue struct {
	Key   string
	Value interface{}
}

KeyValue associates a value with a key.

type OrderedMap

type OrderedMap ast.StructLit

An OrderedMap is a set of key-value pairs that preserves the order in which items were added. It marshals to JSON as an object.

Deprecated: the API now returns an ast.File. This allows OpenAPI to be represented as JSON, YAML, or CUE data, in addition to being able to use all the ast-related tooling.

func (*OrderedMap) MarshalJSON

func (m *OrderedMap) MarshalJSON() (b []byte, err error)

MarshalJSON implements json.Marshaler.

func (*OrderedMap) Pairs

func (m *OrderedMap) Pairs() []KeyValue

Pairs returns the KeyValue pairs associated with m.

func (*OrderedMap) Set

func (m *OrderedMap) Set(key string, x interface{})

Set sets a key value pair. If a pair with the same key already existed, it will be replaced with the new value. Otherwise, the new value is added to the end. The value must be of type string, ast.Expr, or *OrderedMap.

Deprecated: use cuelang.org/go/cue/ast to manipulate ASTs.

func (*OrderedMap) SetAll

func (m *OrderedMap) SetAll(kvs []KeyValue)

SetAll replaces existing key-value pairs with the given ones. The keys must be unique.