generators

README

Generate OpenAPI definitions

• To generate definition for a specific type or package add "+k8s:openapi-gen=true" tag to the type/package comment lines.
• To exclude a type or a member from a tagged package/type, add "+k8s:openapi-gen=false" tag to the comment lines.

OpenAPI Extensions

OpenAPI spec can have extensions on types. To define one or more extensions on a type or its member add +k8s:openapi-gen=x-kubernetes-$NAME:$VALUE to the comment lines before type/member. A type/member can have multiple extensions. The rest of the line in the comment will be used as $VALUE so there is no need to escape or quote the value string. Extensions can be used to pass more information to client generators or documentation generators. For example a type might have a friendly name to be displayed in documentation or being used in a client's fluent interface.

Custom OpenAPI type definitions

Custom types which otherwise don't map directly to OpenAPI can override their OpenAPI definition by implementing a function named "OpenAPIDefinition" with the following signature:

	import openapi "k8s.io/kube-openapi/pkg/common"

	// ...

	type Time struct {
		time.Time
	}

	func (_ Time) OpenAPIDefinition() openapi.OpenAPIDefinition {
		return openapi.OpenAPIDefinition{
			Schema: spec.Schema{
				SchemaProps: spec.SchemaProps{
					Type:   []string{"string"},
					Format: "date-time",
				},
			},
		}
	}

Alternatively, the type can avoid the "openapi" import by defining the following methods. The following example produces the same OpenAPI definition as the example above:

    func (_ Time) OpenAPISchemaType() []string { return []string{"string"} }
    func (_ Time) OpenAPISchemaFormat() string { return "date-time" }

Documentation

Index

• func DefaultNameSystem() string
• func GetTargets(context *generator.Context, args *args.Args) []generator.Target
• func NameSystems() namer.NameSystems
• func ParseCommentTags(t *types.Type, comments []string, prefix string) (*spec.Schema, error)
• type APIRule
• type CELTag
  • func (c *CELTag) Validate() error

Functions

func DefaultNameSystem

func DefaultNameSystem() string

DefaultNameSystem returns the default name system for ordering the types to be processed by the generators in this package.

func GetTargets

func GetTargets(context *generator.Context, args *args.Args) []generator.Target

func NameSystems

func NameSystems() namer.NameSystems

NameSystems returns the name system used by the generators in this package.

func ParseCommentTags

func ParseCommentTags(t *types.Type, comments []string, prefix string) (*spec.Schema, error)

Parses the given comments into a CommentTags type. Validates the parsed comment tags, and returns the result. Accepts an optional type to validate against, and a prefix to filter out markers not related to validation. Accepts a prefix to filter out markers not related to validation. Returns any errors encountered while parsing or validating the comment tags.

Types

type APIRule

type APIRule interface {
	// Validate evaluates API rule on type t and returns a list of field names in
	// the type that violate the rule. Empty field name [""] implies the entire
	// type violates the rule.
	Validate(t *types.Type) ([]string, error)

	// Name returns the name of APIRule
	Name() string
}

APIRule is the interface for validating API rule on Go types

type CELTag

type CELTag struct {
	Rule              string `json:"rule,omitempty"`
	Message           string `json:"message,omitempty"`
	MessageExpression string `json:"messageExpression,omitempty"`
	OptionalOldSelf   *bool  `json:"optionalOldSelf,omitempty"`
	Reason            string `json:"reason,omitempty"`
	FieldPath         string `json:"fieldPath,omitempty"`
}

func (*CELTag) Validate

func (c *CELTag) Validate() error