gnostic_plugin_v1

package
v0.7.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 25, 2023 License: Apache-2.0 Imports: 20 Imported by: 0

README

Plugins

This directory contains support code for building Gnostic plugins and associated examples.

Plugins are used to process API descriptions and can perform tasks like documentation and code generation. Plugins can be written in any language that is supported by the Protocol Buffer tools.

This directory contains several sample plugins and two support tools that make it easier to test plugins by running them standalone.

  • gnostic-plugin-request is a plugin that captures a plugin request and writes it in .json and binary .pb form. When the optional -verbose flag is provided, this plugin logs the request to stdout.
  • gnostic-process-plugin-response is a standalone tool that reads a plugin response on stdin and handles the response in the same way that gnostic does.

For example, this writes the plugin request to local files plugin-request.json and plugin-request.pb.

% gnostic myapi.json --plugin-request-out=.

Then a plugin can be run standalone:

% gnostic-go-generator --plugin < plugin-request.pb > plugin-response.pb

Then you can use the following to process the plugin response:

% gnostic-process-plugin-response -output=. < plugin-response.pb

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	Message_Level_name = map[int32]string{
		0: "UNKNOWN",
		1: "INFO",
		2: "WARNING",
		3: "ERROR",
		4: "FATAL",
	}
	Message_Level_value = map[string]int32{
		"UNKNOWN": 0,
		"INFO":    1,
		"WARNING": 2,
		"ERROR":   3,
		"FATAL":   4,
	}
)

Enum value maps for Message_Level.

View Source
var File_plugins_plugin_proto protoreflect.FileDescriptor

Functions

func HandleResponse

func HandleResponse(response *Response, outputLocation string) error

Types

type Environment

type Environment struct {
	Request         *Request  // plugin request object
	Response        *Response // response message
	Invocation      string    // string representation of call
	RunningAsPlugin bool      // true if app is being run as a plugin
	Verbose         bool      // if true, plugin should log details to stderr
}

Environment contains the environment of a plugin call.

func NewEnvironment

func NewEnvironment() (env *Environment, err error)

NewEnvironment creates a plugin context from arguments and standard input.

func (*Environment) RespondAndExit

func (env *Environment) RespondAndExit()

RespondAndExit serializes and returns the plugin response and then exits.

func (*Environment) RespondAndExitIfError

func (env *Environment) RespondAndExitIfError(err error)

RespondAndExitIfError checks an error and if it is non-nil, records it and serializes and returns the response and then exits.

type File

type File struct {

	// name of the file
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// data to be written to the file
	Data []byte `protobuf:"bytes,2,opt,name=data,proto3" json:"data,omitempty"`
	// contains filtered or unexported fields
}

File describes a file generated by a plugin.

func (*File) Descriptor deprecated

func (*File) Descriptor() ([]byte, []int)

Deprecated: Use File.ProtoReflect.Descriptor instead.

func (*File) GetData

func (x *File) GetData() []byte

func (*File) GetName

func (x *File) GetName() string

func (*File) ProtoMessage

func (*File) ProtoMessage()

func (*File) ProtoReflect added in v0.7.1

func (x *File) ProtoReflect() protoreflect.Message

func (*File) Reset

func (x *File) Reset()

func (*File) String

func (x *File) String() string

type Message added in v0.2.0

type Message struct {

	// message severity
	Level Message_Level `protobuf:"varint,1,opt,name=level,proto3,enum=gnostic.plugin.v1.Message_Level" json:"level,omitempty"`
	// a unique message identifier
	Code string `protobuf:"bytes,2,opt,name=code,proto3" json:"code,omitempty"`
	// message text
	Text string `protobuf:"bytes,3,opt,name=text,proto3" json:"text,omitempty"`
	// an associated key path in an API description
	Keys []string `protobuf:"bytes,4,rep,name=keys,proto3" json:"keys,omitempty"`
	// contains filtered or unexported fields
}

Plugins can return messages to be collated and reported by gnostic.

func (*Message) Descriptor deprecated added in v0.2.0

func (*Message) Descriptor() ([]byte, []int)

Deprecated: Use Message.ProtoReflect.Descriptor instead.

func (*Message) GetCode added in v0.2.0

func (x *Message) GetCode() string

func (*Message) GetKeys added in v0.2.0

func (x *Message) GetKeys() []string

func (*Message) GetLevel added in v0.2.0

func (x *Message) GetLevel() Message_Level

func (*Message) GetText added in v0.2.0

func (x *Message) GetText() string

func (*Message) ProtoMessage added in v0.2.0

func (*Message) ProtoMessage()

func (*Message) ProtoReflect added in v0.7.1

func (x *Message) ProtoReflect() protoreflect.Message

func (*Message) Reset added in v0.2.0

func (x *Message) Reset()

func (*Message) String added in v0.2.0

func (x *Message) String() string

type Message_Level added in v0.2.0

type Message_Level int32
const (
	Message_UNKNOWN Message_Level = 0
	Message_INFO    Message_Level = 1
	Message_WARNING Message_Level = 2
	Message_ERROR   Message_Level = 3
	Message_FATAL   Message_Level = 4
)

func (Message_Level) Descriptor added in v0.7.1

func (Message_Level) Enum added in v0.7.1

func (x Message_Level) Enum() *Message_Level

func (Message_Level) EnumDescriptor deprecated added in v0.2.0

func (Message_Level) EnumDescriptor() ([]byte, []int)

Deprecated: Use Message_Level.Descriptor instead.

func (Message_Level) Number added in v0.7.1

func (Message_Level) String added in v0.2.0

func (x Message_Level) String() string

func (Message_Level) Type added in v0.7.1

type Messages added in v0.2.0

type Messages struct {
	Messages []*Message `protobuf:"bytes,1,rep,name=messages,proto3" json:"messages,omitempty"`
	// contains filtered or unexported fields
}

func (*Messages) Descriptor deprecated added in v0.2.0

func (*Messages) Descriptor() ([]byte, []int)

Deprecated: Use Messages.ProtoReflect.Descriptor instead.

func (*Messages) GetMessages added in v0.2.0

func (x *Messages) GetMessages() []*Message

func (*Messages) ProtoMessage added in v0.2.0

func (*Messages) ProtoMessage()

func (*Messages) ProtoReflect added in v0.7.1

func (x *Messages) ProtoReflect() protoreflect.Message

func (*Messages) Reset added in v0.2.0

func (x *Messages) Reset()

func (*Messages) String added in v0.2.0

func (x *Messages) String() string

type Parameter

type Parameter struct {

	// The name of the parameter as specified in the option string
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// The parameter value as specified in the option string
	Value string `protobuf:"bytes,2,opt,name=value,proto3" json:"value,omitempty"`
	// contains filtered or unexported fields
}

A parameter passed to the plugin from (or through) gnostic.

func (*Parameter) Descriptor deprecated

func (*Parameter) Descriptor() ([]byte, []int)

Deprecated: Use Parameter.ProtoReflect.Descriptor instead.

func (*Parameter) GetName

func (x *Parameter) GetName() string

func (*Parameter) GetValue

func (x *Parameter) GetValue() string

func (*Parameter) ProtoMessage

func (*Parameter) ProtoMessage()

func (*Parameter) ProtoReflect added in v0.7.1

func (x *Parameter) ProtoReflect() protoreflect.Message

func (*Parameter) Reset

func (x *Parameter) Reset()

func (*Parameter) String

func (x *Parameter) String() string

type Request

type Request struct {

	// filename or URL of the original source document
	SourceName string `protobuf:"bytes,1,opt,name=source_name,json=sourceName,proto3" json:"source_name,omitempty"`
	// Output path specified in the plugin invocation.
	OutputPath string `protobuf:"bytes,2,opt,name=output_path,json=outputPath,proto3" json:"output_path,omitempty"`
	// Plugin parameters parsed from the invocation string.
	Parameters []*Parameter `protobuf:"bytes,3,rep,name=parameters,proto3" json:"parameters,omitempty"`
	// The version number of gnostic.
	CompilerVersion *Version `protobuf:"bytes,4,opt,name=compiler_version,json=compilerVersion,proto3" json:"compiler_version,omitempty"`
	// API models
	Models []*anypb.Any `protobuf:"bytes,5,rep,name=models,proto3" json:"models,omitempty"`
	// contains filtered or unexported fields
}

An encoded Request is written to the plugin's stdin.

func (*Request) AddModel added in v0.2.0

func (request *Request) AddModel(modelType string, model proto.Message) error

func (*Request) Descriptor deprecated

func (*Request) Descriptor() ([]byte, []int)

Deprecated: Use Request.ProtoReflect.Descriptor instead.

func (*Request) GetCompilerVersion

func (x *Request) GetCompilerVersion() *Version

func (*Request) GetModels added in v0.2.0

func (x *Request) GetModels() []*anypb.Any

func (*Request) GetOutputPath

func (x *Request) GetOutputPath() string

func (*Request) GetParameters

func (x *Request) GetParameters() []*Parameter

func (*Request) GetSourceName

func (x *Request) GetSourceName() string

func (*Request) ProtoMessage

func (*Request) ProtoMessage()

func (*Request) ProtoReflect added in v0.7.1

func (x *Request) ProtoReflect() protoreflect.Message

func (*Request) Reset

func (x *Request) Reset()

func (*Request) String

func (x *Request) String() string

type Response

type Response struct {

	// Error message.  If non-empty, the plugin failed.
	// The plugin process should exit with status code zero
	// even if it reports an error in this way.
	//
	// This should be used to indicate errors which prevent the plugin from
	// operating as intended.  Errors which indicate a problem in gnostic
	// itself -- such as the input Document being unparseable -- should be
	// reported by writing a message to stderr and exiting with a non-zero
	// status code.
	Errors []string `protobuf:"bytes,1,rep,name=errors,proto3" json:"errors,omitempty"`
	// file output, each file will be written by gnostic to an appropriate
	// location.
	Files []*File `protobuf:"bytes,2,rep,name=files,proto3" json:"files,omitempty"`
	// informational messages to be collected and reported by gnostic.
	Messages []*Message `protobuf:"bytes,3,rep,name=messages,proto3" json:"messages,omitempty"`
	// contains filtered or unexported fields
}

The plugin writes an encoded Response to stdout.

func (*Response) Descriptor deprecated

func (*Response) Descriptor() ([]byte, []int)

Deprecated: Use Response.ProtoReflect.Descriptor instead.

func (*Response) GetErrors

func (x *Response) GetErrors() []string

func (*Response) GetFiles

func (x *Response) GetFiles() []*File

func (*Response) GetMessages added in v0.2.0

func (x *Response) GetMessages() []*Message

func (*Response) ProtoMessage

func (*Response) ProtoMessage()

func (*Response) ProtoReflect added in v0.7.1

func (x *Response) ProtoReflect() protoreflect.Message

func (*Response) Reset

func (x *Response) Reset()

func (*Response) String

func (x *Response) String() string

type Version

type Version struct {
	Major int32 `protobuf:"varint,1,opt,name=major,proto3" json:"major,omitempty"`
	Minor int32 `protobuf:"varint,2,opt,name=minor,proto3" json:"minor,omitempty"`
	Patch int32 `protobuf:"varint,3,opt,name=patch,proto3" json:"patch,omitempty"`
	// A suffix for alpha, beta or rc release, e.g., "alpha-1", "rc2". It should
	// be empty for mainline stable releases.
	Suffix string `protobuf:"bytes,4,opt,name=suffix,proto3" json:"suffix,omitempty"`
	// contains filtered or unexported fields
}

The version number of gnostic.

func (*Version) Descriptor deprecated

func (*Version) Descriptor() ([]byte, []int)

Deprecated: Use Version.ProtoReflect.Descriptor instead.

func (*Version) GetMajor

func (x *Version) GetMajor() int32

func (*Version) GetMinor

func (x *Version) GetMinor() int32

func (*Version) GetPatch

func (x *Version) GetPatch() int32

func (*Version) GetSuffix

func (x *Version) GetSuffix() string

func (*Version) ProtoMessage

func (*Version) ProtoMessage()

func (*Version) ProtoReflect added in v0.7.1

func (x *Version) ProtoReflect() protoreflect.Message

func (*Version) Reset

func (x *Version) Reset()

func (*Version) String

func (x *Version) String() string

Directories

Path Synopsis
gnostic_analyze is a tool for analyzing OpenAPI descriptions.
gnostic_analyze is a tool for analyzing OpenAPI descriptions.
summarize
summarize is a tool for summarizing the results of gnostic_analyze runs.
summarize is a tool for summarizing the results of gnostic_analyze runs.
gnostic-complexity is a plugin that generates a complexity summary of an API.
gnostic-complexity is a plugin that generates a complexity summary of an API.
gnostic-plugin-request is a development tool that captures and optionally displays the contents of the gnostic plugin interface.
gnostic-plugin-request is a development tool that captures and optionally displays the contents of the gnostic plugin interface.
gnostic-process-plugin-response is a development tool that processes the output of a gnostic plugin in the same way that it would be handled by gnostic itself.
gnostic-process-plugin-response is a development tool that processes the output of a gnostic plugin in the same way that it would be handled by gnostic itself.
gnostic_go_generator is a sample Gnostic plugin that generates Go code that supports an API.
gnostic_go_generator is a sample Gnostic plugin that generates Go code that supports an API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL