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 ¶
- Variables
- func HandleResponse(response *Response, outputLocation string) error
- type Environment
- type File
- type Message
- func (*Message) Descriptor() ([]byte, []int)deprecated
- func (x *Message) GetCode() string
- func (x *Message) GetKeys() []string
- func (x *Message) GetLevel() Message_Level
- func (x *Message) GetText() string
- func (*Message) ProtoMessage()
- func (x *Message) ProtoReflect() protoreflect.Message
- func (x *Message) Reset()
- func (x *Message) String() string
- type Message_Level
- func (Message_Level) Descriptor() protoreflect.EnumDescriptor
- func (x Message_Level) Enum() *Message_Level
- func (Message_Level) EnumDescriptor() ([]byte, []int)deprecated
- func (x Message_Level) Number() protoreflect.EnumNumber
- func (x Message_Level) String() string
- func (Message_Level) Type() protoreflect.EnumType
- type Messages
- type Parameter
- type Request
- func (request *Request) AddModel(modelType string, model proto.Message) error
- func (*Request) Descriptor() ([]byte, []int)deprecated
- func (x *Request) GetCompilerVersion() *Version
- func (x *Request) GetModels() []*anypb.Any
- func (x *Request) GetOutputPath() string
- func (x *Request) GetParameters() []*Parameter
- func (x *Request) GetSourceName() string
- func (*Request) ProtoMessage()
- func (x *Request) ProtoReflect() protoreflect.Message
- func (x *Request) Reset()
- func (x *Request) String() string
- type Response
- func (*Response) Descriptor() ([]byte, []int)deprecated
- func (x *Response) GetErrors() []string
- func (x *Response) GetFiles() []*File
- func (x *Response) GetMessages() []*Message
- func (*Response) ProtoMessage()
- func (x *Response) ProtoReflect() protoreflect.Message
- func (x *Response) Reset()
- func (x *Response) String() string
- type Version
- func (*Version) Descriptor() ([]byte, []int)deprecated
- func (x *Version) GetMajor() int32
- func (x *Version) GetMinor() int32
- func (x *Version) GetPatch() int32
- func (x *Version) GetSuffix() string
- func (*Version) ProtoMessage()
- func (x *Version) ProtoReflect() protoreflect.Message
- func (x *Version) Reset()
- func (x *Version) String() string
Constants ¶
This section is empty.
Variables ¶
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.
var File_plugins_plugin_proto protoreflect.FileDescriptor
Functions ¶
func HandleResponse ¶
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) ProtoMessage ¶
func (*File) ProtoMessage()
func (*File) ProtoReflect ¶
func (x *File) ProtoReflect() protoreflect.Message
type Message ¶
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
func (*Message) GetLevel ¶
func (x *Message) GetLevel() Message_Level
func (*Message) ProtoMessage ¶
func (*Message) ProtoMessage()
func (*Message) ProtoReflect ¶
func (x *Message) ProtoReflect() protoreflect.Message
type Message_Level ¶
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 ¶
func (Message_Level) Descriptor() protoreflect.EnumDescriptor
func (Message_Level) Enum ¶
func (x Message_Level) Enum() *Message_Level
func (Message_Level) EnumDescriptor
deprecated
func (Message_Level) EnumDescriptor() ([]byte, []int)
Deprecated: Use Message_Level.Descriptor instead.
func (Message_Level) Number ¶
func (x Message_Level) Number() protoreflect.EnumNumber
func (Message_Level) String ¶
func (x Message_Level) String() string
func (Message_Level) Type ¶
func (Message_Level) Type() protoreflect.EnumType
type Messages ¶
type Messages struct { Messages []*Message `protobuf:"bytes,1,rep,name=messages,proto3" json:"messages,omitempty"` // contains filtered or unexported fields }
func (*Messages) Descriptor
deprecated
func (*Messages) GetMessages ¶
func (*Messages) ProtoMessage ¶
func (*Messages) ProtoMessage()
func (*Messages) ProtoReflect ¶
func (x *Messages) ProtoReflect() protoreflect.Message
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) ProtoMessage ¶
func (*Parameter) ProtoMessage()
func (*Parameter) ProtoReflect ¶
func (x *Parameter) ProtoReflect() protoreflect.Message
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) Descriptor
deprecated
func (*Request) GetCompilerVersion ¶
func (*Request) GetOutputPath ¶
func (*Request) GetParameters ¶
func (*Request) GetSourceName ¶
func (*Request) ProtoMessage ¶
func (*Request) ProtoMessage()
func (*Request) ProtoReflect ¶
func (x *Request) ProtoReflect() protoreflect.Message
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) GetMessages ¶
func (*Response) ProtoMessage ¶
func (*Response) ProtoMessage()
func (*Response) ProtoReflect ¶
func (x *Response) ProtoReflect() protoreflect.Message
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) ProtoMessage ¶
func (*Version) ProtoMessage()
func (*Version) ProtoReflect ¶
func (x *Version) ProtoReflect() protoreflect.Message
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. |