docgen

Documentation

Index

• Variables
• type AttributeType
• type FunctionDefinition
• type FunctionParameter
• type FunctionReturn
• type PluginDocResourceSpec
• type PluginDocResourceSpecSchema
• type PluginDocs
  • func GeneratePluginDocs(pluginID string, pluginInstance any, manager pluginservicev1.Manager, ...) (*PluginDocs, error)
• type PluginDocsCustomVarType
• type PluginDocsCustomVarTypeOption
• type PluginDocsDataSource
• type PluginDocsDataSourceFieldSpec
• type PluginDocsDataSourceSpec
• type PluginDocsFunction
• type PluginDocsLink
• type PluginDocsLinkAnnotationDefinition
• type PluginDocsResource
• type PluginDocsVersionConfig
• type PluginDocsVersionConfigField
• type ValueTypeDefinition

Variables

var (
	// ErrInvalidPluginType is returned when the resolved plugin is not
	// of the allowed types.
	ErrInvalidPluginType = errors.New(
		"invalid plugin type for plugin instance, plugin must implement one of the " +
			"`provider.Provider` or `transform.SpecTransformer` interfaces",
	)

	// ErrPluginMetadataNotFound is returned when the plugin metadata
	// could not be found in the plugin manager.
	ErrPluginMetadataNotFound = errors.New(
		"plugin metadata not found, this is required to produce documentation",
	)
)

Types

type AttributeType

type AttributeType struct {
	ValueTypeDefinition
	Nullable bool `json:"nullable"`
}

type FunctionDefinition

type FunctionDefinition struct {
	Parameters []*FunctionParameter `json:"parameters"`
	Return     *FunctionReturn      `json:"return"`
}

type FunctionParameter

type FunctionParameter struct {
	ParamType      string `json:"paramType"`
	Name           string `json:"name,omitempty"`
	Label          string `json:"label,omitempty"`
	Description    string `json:"description,omitempty"`
	AllowNullValue bool   `json:"allowNullValue"`
	Optional       bool   `json:"optional"`

	// This should only be present for scalar, object, function and variadic parameters.
	ValueTypeDefinition *ValueTypeDefinition `json:"valueTypeDefinition,omitempty"`

	// This should only be present for list parameters.
	ElementValueTypeDefinition *ValueTypeDefinition `json:"elementValueTypeDefinition,omitempty"`

	// This should only be present for map parameters.
	MapValueTypeDefinition *ValueTypeDefinition `json:"mapValueTypeDefinition,omitempty"`

	// This should only be present for "any" parameters that are union types.
	UnionValueTypeDefinitions []*ValueTypeDefinition `json:"unionValueTypeDefinitions,omitempty"`

	// The following fields should only present for variadic parameters.
	VariadicSingleType bool `json:"singleType,omitempty"`
	VariadicNamed      bool `json:"named,omitempty"`
}

type FunctionReturn

type FunctionReturn struct {
	ReturnType  string `json:"returnType"`
	Description string `json:"description,omitempty"`

	// This should only be present for scalar, object, function return types.
	ValueTypeDefinition *ValueTypeDefinition `json:"valueTypeDefinition,omitempty"`

	// This should only be present for list return types.
	ElementValueTypeDefinition *ValueTypeDefinition `json:"elementValueTypeDefinition,omitempty"`

	// This should only be present for map return types.
	MapValueTypeDefinition *ValueTypeDefinition `json:"mapValueTypeDefinition,omitempty"`

	// This should only be present for "any" return types that are union types.
	UnionValueTypeDefinitions []*ValueTypeDefinition `json:"unionValueTypeDefinitions,omitempty"`
}

type PluginDocResourceSpec

type PluginDocResourceSpec struct {
	Schema  *PluginDocResourceSpecSchema `json:"schema"`
	IDField string                       `json:"idField"`
}

type PluginDocResourceSpecSchema

type PluginDocResourceSpecSchema struct {
	Type         string              `json:"type"`
	Label        string              `json:"label"`
	Description  string              `json:"description"`
	Nullable     bool                `json:"nullable"`
	Computed     bool                `json:"computed"`
	MustRecreate bool                `json:"mustRecreate"`
	Default      *core.MappingNode   `json:"default,omitempty"`
	Examples     []*core.MappingNode `json:"examples,omitempty"`

	// Required for "object" types, should be empty for other types.
	Attributes map[string]*PluginDocResourceSpecSchema `json:"attributes,omitempty"`
	// Required for "object" types, should be empty for other types.
	// This is a list of required attributes.
	Required []string `json:"required,omitempty"`

	// Required for "map" types, should be empty for other types.
	MapValues *PluginDocResourceSpecSchema `json:"mapValues,omitempty"`

	// Required for "array" types, should be empty for other types.
	Items *PluginDocResourceSpecSchema `json:"listValues,omitempty"`

	// Required for "union" types, should be empty for other types.
	OneOf []*PluginDocResourceSpecSchema `json:"oneOf,omitempty"`
}

type PluginDocs

type PluginDocs struct {
	ID               string                   `json:"id"`
	DisplayName      string                   `json:"displayName"`
	Version          string                   `json:"version"`
	ProtocolVersions []string                 `json:"protocolVersions"`
	Description      string                   `json:"description"`
	Author           string                   `json:"author"`
	Repository       string                   `json:"repository"`
	Config           *PluginDocsVersionConfig `json:"config"`

	// Required for providers, should be empty for transformers.
	Resources []*PluginDocsResource `json:"resources,omitempty"`
	// Required for providers, should be empty for transformers.
	Links []*PluginDocsLink `json:"links,omitempty"`
	// Required for providers, should be empty for transformers.
	DataSources []*PluginDocsDataSource `json:"dataSources,omitempty"`
	// Required for providers, should be empty for transformers.
	CustomVarTypes []*PluginDocsCustomVarType `json:"customVarTypes,omitempty"`
	// Required for providers, should be empty for transformers.
	Functions []*PluginDocsFunction `json:"functions,omitempty"`

	// Required for transformers, should be empty for providers.
	TransformName string `json:"transformName,omitempty"`
	// Required for transformers, should be empty for providers.
	AbstractResources []*PluginDocsResource `json:"abstractResources,omitempty"`
}

PluginDocs is a struct that holds the JSON representation of the plugin documentation.

func GeneratePluginDocs

func GeneratePluginDocs(
	pluginID string,
	pluginInstance any,
	manager pluginservicev1.Manager,
	envConfig *env.Config,
) (*PluginDocs, error)

GenerateProviderDocs generates documentation for a provider or transformer plugin.

type PluginDocsCustomVarType

type PluginDocsCustomVarType struct {
	Type        string                                    `json:"type"`
	Label       string                                    `json:"label"`
	Summary     string                                    `json:"summary"`
	Description string                                    `json:"description"`
	Options     map[string]*PluginDocsCustomVarTypeOption `json:"options"`
	Examples    []string                                  `json:"examples,omitempty"`
}

type PluginDocsCustomVarTypeOption

type PluginDocsCustomVarTypeOption struct {
	Label       string `json:"label"`
	Description string `json:"value"`
}

type PluginDocsDataSource

type PluginDocsDataSource struct {
	Type          string                    `json:"type"`
	Label         string                    `json:"label"`
	Summary       string                    `json:"summary"`
	Description   string                    `json:"description"`
	Specification *PluginDocsDataSourceSpec `json:"specification"`
	Examples      []string                  `json:"examples,omitempty"`
}

type PluginDocsDataSourceFieldSpec

type PluginDocsDataSourceFieldSpec struct {
	Type        string `json:"type"`
	Description string `json:"description"`
	Nullable    bool   `json:"nullable"`
	Filterable  bool   `json:"filterable"`
}

type PluginDocsDataSourceSpec

type PluginDocsDataSourceSpec struct {
	Fields map[string]*PluginDocsDataSourceFieldSpec `json:"fields"`
}

type PluginDocsFunction

type PluginDocsFunction struct {
	FunctionDefinition
	Name        string `json:"name"`
	Summary     string `json:"summary"`
	Description string `json:"description"`
}

type PluginDocsLink

type PluginDocsLink struct {
	Type                  string                                         `json:"type"`
	Summary               string                                         `json:"summary"`
	Description           string                                         `json:"description"`
	AnnotationDefinitions map[string]*PluginDocsLinkAnnotationDefinition `json:"annotationDefinitions"`
}

type PluginDocsLinkAnnotationDefinition

type PluginDocsLinkAnnotationDefinition struct {
	Name          string              `json:"name"`
	Label         string              `json:"label"`
	Type          string              `json:"type"`
	Description   string              `json:"description"`
	Default       *core.ScalarValue   `json:"default,omitempty"`
	AllowedValues []*core.ScalarValue `json:"allowedValues,omitempty"`
	Examples      []*core.ScalarValue `json:"examples,omitempty"`
	Required      bool                `json:"required"`
}

type PluginDocsResource

type PluginDocsResource struct {
	Type          string                 `json:"type"`
	Label         string                 `json:"label"`
	Summary       string                 `json:"summary"`
	Description   string                 `json:"description"`
	Specification *PluginDocResourceSpec `json:"specification"`
	Examples      []string               `json:"examples"`
	CanLinkTo     []string               `json:"canLinkTo"`
}

type PluginDocsVersionConfig

type PluginDocsVersionConfig struct {
	Fields                map[string]*PluginDocsVersionConfigField `json:"fields"`
	AllowAdditionalFields bool                                     `json:"allowAdditionalFields"`
}

type PluginDocsVersionConfigField

type PluginDocsVersionConfigField struct {
	Type          string              `json:"type"`
	Label         string              `json:"label"`
	Description   string              `json:"description"`
	Required      bool                `json:"required"`
	Default       *core.ScalarValue   `json:"default,omitempty"`
	AllowedValues []*core.ScalarValue `json:"allowedValues,omitempty"`
	Secret        bool                `json:"secret"`
	Examples      []*core.ScalarValue `json:"examples,omitempty"`
}

type ValueTypeDefinition

type ValueTypeDefinition struct {
	Type        string `json:"type"`
	Label       string `json:"label,omitempty"`
	Description string `json:"description,omitempty"`

	// This should only be present for "string" scalar types.
	StringChoices []string `json:"stringChoices,omitempty"`

	// This should only be present for list types.
	ElementValueTypeDefinition *ValueTypeDefinition `json:"elementValueTypeDefinition,omitempty"`

	// This should only be present for map types.
	MapValueTypeDefinition *ValueTypeDefinition `json:"mapValueTypeDefinition,omitempty"`

	// This should only be present for object types.
	AttributeValueTypeDefinitions map[string]*AttributeType `json:"attributeValueTypeDefinitions,omitempty"`

	// This should only be present for function types.
	FunctionDefinition *FunctionDefinition `json:"functionDefinition,omitempty"`

	// This should only be present for "any" types that are union types.
	UnionValueTypeDefinitions []*ValueTypeDefinition `json:"unionValueTypeDefinitions,omitempty"`
}