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

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{}

	// 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

	// StrictFeatures reports an error for features that are known
	// to be unsupported.
	StrictFeatures bool

	// StrictKeywords reports an error when unknown keywords
	// are encountered. For OpenAPI 3.0, this is implicitly always
	// true, as that specification explicitly prohibits unknown keywords
	// other than "x-" prefixed keywords.
	StrictKeywords bool
}

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

type Generator

type Generator = Config