jrpc_doc

package
v0.1.7 Latest Latest
Warning

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

 Go to latest Published: Apr 17, 2024 License: Apache-2.0, MIT Imports: 21 Imported by: 0

README

protoc-gen-jrpc-doc

protoc-gen-jrpc-doc-doc generates json-rpc document from .proto specs

Run Example

make install && make proto

Documentation

Overview

Package jrpc_doc is a protoc plugin for generating documentation from your proto files.

Typically this will not be used as a library, though nothing prevents that. Normally it'll be invoked by passing `--doc_out` and `--doc_opt` values to protoc.

Example: generate HTML documentation 

protoc --doc_out=. --doc_opt=html,index.html protos/*.proto

Example: exclude patterns 

protoc --doc_out=. --doc_opt=html,index.html:google/*,somedir/* protos/*.proto

Example: use a custom template 

protoc --doc_out=. --doc_opt=custom.tmpl,docs.txt protos/*.proto

For more details, check out the README at https://github.com/pacviewer/jrpc-gateway/protoc-gen-jrpc-doc

Index

Constants

View Source 
const VERSION = "0.0.1"

VERSION is the version of protoc-gen-jrpc-doc being used.

Variables

View Source 
var SupportedFeatures = uint64(plugin_go.CodeGeneratorResponse_FEATURE_PROTO3_OPTIONAL)

SupportedFeatures describes a flag setting for supported features.

Functions

func AnchorFilter 

func AnchorFilter(str string) string

AnchorFilter replaces all special characters with URL friendly dashes

func FullTypeName 

func FullTypeName(t string, isRepeated, isMap bool) string

func Minus 

func Minus(a, b int) int

func NoBrFilter 

func NoBrFilter(content string) string

NoBrFilter removes single CR and LF from content.

func PFilter 

func PFilter(content string) template.HTML

PFilter splits the content by new lines and wraps each one in a <p> tag.

func ParaFilter 

func ParaFilter(content string) string

ParaFilter splits the content by new lines and wraps each one in a <para> tag.

func RenderTemplate 

func RenderTemplate(kind RenderType, template *Template, inputTemplate string) ([]byte, error)

RenderTemplate renders the template based on the render type. It supports overriding the default input templates by supplying a non-empty string as the last parameter.

Example: generating an HTML template (assuming you've got a Template object) 

data, err := RenderTemplate(RenderTypeHTML, &template, "")

Example: generating a custom template (assuming you've got a Template object) 

data, err := RenderTemplate(RenderTypeHTML, &template, "{{range .Files}}{{.Name}}{{end}}")

func RpcMethod 

func RpcMethod(pkg, service, method string) string

func ToJsonRpc 

func ToJsonRpc(text string, protoMethod string) string

Types

type Enum 

type Enum struct {
	Name        string       `json:"name"`
	LongName    string       `json:"longName"`
	FullName    string       `json:"fullName"`
	Description string       `json:"description"`
	Values      []*EnumValue `json:"values"`

	Options map[string]interface{} `json:"options,omitempty"`
}

Enum contains details about enumerations. These can be either top level enums, or nested (defined within a message).

func (Enum) Option 

func (e Enum) Option(name string) interface{}

Option returns the named option.

func (Enum) ValueOptions 

func (e Enum) ValueOptions() []string

ValueOptions returns all options that are set on the values in this enum.

func (Enum) ValuesWithOption 

func (e Enum) ValuesWithOption(optionName string) []*EnumValue

ValuesWithOption returns all values that have the given option set. If no single value has the option set, this returns nil.

type EnumValue 

type EnumValue struct {
	Name        string `json:"name"`
	Number      string `json:"number"`
	Description string `json:"description"`

	Options map[string]interface{} `json:"options,omitempty"`
}

EnumValue contains details about an individual value within an enumeration.

func (EnumValue) Option 

func (v EnumValue) Option(name string) interface{}

Option returns the named option.

type File 

type File struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Package     string `json:"package"`

	HasEnums      bool `json:"hasEnums"`
	HasExtensions bool `json:"hasExtensions"`
	HasMessages   bool `json:"hasMessages"`
	HasServices   bool `json:"hasServices"`

	Enums      orderedEnums      `json:"enums"`
	Extensions orderedExtensions `json:"extensions"`
	Messages   orderedMessages   `json:"messages"`
	Services   orderedServices   `json:"services"`

	Options map[string]interface{} `json:"options,omitempty"`
}

File wraps all the relevant parsed info about a proto file. File objects guarantee that their top-level enums, extensions, messages, and services are sorted alphabetically based on their "long name". Other values (enum values, fields, service methods) will be in the order that they're defined within their respective proto files.

In the case of proto3 files, HasExtensions will always be false, and Extensions will be empty.

func (File) Option 

func (f File) Option(name string) interface{}

Option returns the named option.

type FileExtension 

type FileExtension struct {
	Name               string `json:"name"`
	LongName           string `json:"longName"`
	FullName           string `json:"fullName"`
	Description        string `json:"description"`
	Label              string `json:"label"`
	Type               string `json:"type"`
	LongType           string `json:"longType"`
	FullType           string `json:"fullType"`
	Number             int    `json:"number"`
	DefaultValue       string `json:"defaultValue"`
	ContainingType     string `json:"containingType"`
	ContainingLongType string `json:"containingLongType"`
	ContainingFullType string `json:"containingFullType"`
}

FileExtension contains details about top-level extensions within a proto(2) file.

type JDict 

type JDict = map[string]map[string]any
var (
	Jdict JDict   = JDict{}
	Files []*File = []*File{}
)

type JsonType 

type JsonType = string
const (
	ObjectJsonType         JsonType = "json object"
	ArrayJsonType          JsonType = "json array"
	NumericJsonType        JsonType = "numeric"
	StringJsonType         JsonType = "string"
	BoolJsonType           JsonType = "boolean"
	KeyValueObjectJsonType JsonType = "key:value json object"
)

type Message 

type Message struct {
	Name        string `json:"name"`
	LongName    string `json:"longName"`
	FullName    string `json:"fullName"`
	Description string `json:"description"`

	HasExtensions bool `json:"hasExtensions"`
	HasFields     bool `json:"hasFields"`
	HasOneofs     bool `json:"hasOneofs"`

	Extensions []*MessageExtension `json:"extensions"`
	Fields     []*MessageField     `json:"fields"`

	Options map[string]interface{} `json:"options,omitempty"`
}

Message contains details about a protobuf message.

In the case of proto3 files, HasExtensions will always be false, and Extensions will be empty.

func (Message) FieldOptions 

func (m Message) FieldOptions() []string

FieldOptions returns all options that are set on the fields in this message.

func (Message) FieldsWithOption 

func (m Message) FieldsWithOption(optionName string) []*MessageField

FieldsWithOption returns all fields that have the given option set. If no single value has the option set, this returns nil.

func (Message) Option 

func (m Message) Option(name string) interface{}

Option returns the named option.

type MessageExtension 

type MessageExtension struct {
	FileExtension

	ScopeType     string `json:"scopeType"`
	ScopeLongType string `json:"scopeLongType"`
	ScopeFullType string `json:"scopeFullType"`
}

MessageExtension contains details about message-scoped extensions in proto(2) files.

type MessageField 

type MessageField struct {
	Name         string `json:"name"`
	Description  string `json:"description"`
	Label        string `json:"label"`
	Type         string `json:"type"`
	LongType     string `json:"longType"`
	FullType     string `json:"fullType"`
	IsMap        bool   `json:"ismap"`
	IsRepeated   bool   `json:"isRepeated"`
	IsOneof      bool   `json:"isoneof"`
	OneofDecl    string `json:"oneofdecl"`
	DefaultValue string `json:"defaultValue"`

	Options map[string]interface{} `json:"options,omitempty"`
}

MessageField contains details about an individual field within a message.

In the case of proto3 files, DefaultValue will always be empty. Similarly, label will be empty unless the field is repeated (in which case it'll be "repeated").

func (MessageField) Option 

func (f MessageField) Option(name string) interface{}

Option returns the named option.

type Param 

type Param struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Type        string `json:"type"`
	Constraints string `json:"constraints"`
}

Param is json-rpc friendly param for service methods.

type Plugin 

type Plugin struct{}

Plugin describes a protoc code generate plugin. It's an implementation of Plugin from github.com/pseudomuto/protokit

func (*Plugin) Generate 

func (p *Plugin) Generate(r *plugin_go.CodeGeneratorRequest) (*plugin_go.CodeGeneratorResponse, error)

Generate compiles the documentation and generates the CodeGeneratorResponse to send back to protoc. It does this by rendering a template based on the options parsed from the CodeGeneratorRequest.

type PluginOptions 

type PluginOptions struct {
	Type            RenderType
	TemplateFile    string
	OutputFile      string
	ExcludePatterns []*regexp.Regexp
	SourceRelative  bool
	DictLocation    string
	ApiEndpoint     string
}

PluginOptions encapsulates options for the plugin. The type of renderer, template file, and the name of the output file are included.

func ParseOptions 

func ParseOptions(req *plugin_go.CodeGeneratorRequest) (*PluginOptions, error)

ParseOptions parses plugin options from a CodeGeneratorRequest. It does this by splitting the `Parameter` field from the request object and parsing out the type of renderer to use and the name of the file to be generated.

The parameter (`--doc_opt`) must be of the format <TYPE|TEMPLATE_FILE>,<OUTPUT_FILE>[,default|source_relative]:<EXCLUDE_PATTERN>,<EXCLUDE_PATTERN>*. The file will be written to the directory specified with the `--doc_out` argument to protoc.

type Processor 

type Processor interface {
	Apply(template *Template) ([]byte, error)
}

Processor is an interface that is satisfied by all built-in processors (text, html, and json).

type RenderType 

type RenderType int8

RenderType is an "enum" for which type of renderer to use. 

const (
	RenderTypeDocBook RenderType
	RenderTypeHTML
	RenderTypeJSON
	RenderTypeMarkdown
)

Available render types.

func NewRenderType 

func NewRenderType(renderType string) (RenderType, error)

NewRenderType creates a RenderType from the supplied string. If the type is not known, (0, error) is returned. It is assumed (by the plugin) that invalid render type simply means that the path to a custom template was supplied.

type ScalarValue 

type ScalarValue struct {
	ProtoType  string `json:"protoType"`
	Notes      string `json:"notes"`
	CppType    string `json:"cppType"`
	CSharp     string `json:"csType"`
	GoType     string `json:"goType"`
	JavaType   string `json:"javaType"`
	PhpType    string `json:"phpType"`
	PythonType string `json:"pythonType"`
	RubyType   string `json:"rubyType"`
}

ScalarValue contains information about scalar value types in protobuf. The common use case for this type is to know which language specific type maps to the protobuf type.

For example, the protobuf type `int64` maps to `long` in C#, and `Bignum` in Ruby. For the full list, take a look at https://developers.google.com/protocol-buffers/docs/proto3#scalar

type Service 

type Service struct {
	Name        string           `json:"name"`
	LongName    string           `json:"longName"`
	FullName    string           `json:"fullName"`
	Description string           `json:"description"`
	Methods     []*ServiceMethod `json:"methods"`

	Options map[string]interface{} `json:"options,omitempty"`
}

Service contains details about a service definition within a proto file.

func (Service) MethodOptions 

func (s Service) MethodOptions() []string

MethodOptions returns all options that are set on the methods in this service.

func (Service) MethodsWithOption 

func (s Service) MethodsWithOption(optionName string) []*ServiceMethod

MethodsWithOption returns all methods that have the given option set. If no single method has the option set, this returns nil.

func (Service) Option 

func (s Service) Option(name string) interface{}

Option returns the named option.

type ServiceMethod 

type ServiceMethod struct {
	Name              string `json:"name"`
	Description       string `json:"description"`
	RequestType       string `json:"requestType"`
	RequestLongType   string `json:"requestLongType"`
	RequestFullType   string `json:"requestFullType"`
	RequestStreaming  bool   `json:"requestStreaming"`
	ResponseType      string `json:"responseType"`
	ResponseLongType  string `json:"responseLongType"`
	ResponseFullType  string `json:"responseFullType"`
	ResponseStreaming bool   `json:"responseStreaming"`

	RequestMessage  *Message `json:"requestMessage"`
	ResponseMessage *Message `json:"responseMessage"`

	Params string `json:"parameters"`
	Result string `json:"result"`

	Options map[string]interface{} `json:"options,omitempty"`
}

ServiceMethod contains details about an individual method within a service.

func (ServiceMethod) Option 

func (m ServiceMethod) Option(name string) interface{}

Option returns the named option.

type Template 

type Template struct {
	// The files that were parsed
	Files []*File `json:"files"`
	// Details about the scalar values and their respective types in supported languages.
	Scalars []*ScalarValue `json:"scalarValueTypes"`
	// JDict is fields placeholders
	JDict JDict
}

Template is a type for encapsulating all the parsed files, messages, fields, enums, services, extensions, etc. into an object that will be supplied to a go template.

func NewTemplate 

func NewTemplate(descs []*protokit.FileDescriptor, jdict JDict) *Template

NewTemplate creates a Template object from a set of descriptors.

type Type 

type Type = string
const (
	ObjectType  Type = "object"
	ArrayType   Type = "array"
	StringType  Type = "string"
	NumericType Type = "numeric"
)

Source Files

View all Source files

Directories

Path Synopsis
cmd
protoc-gen-jrpc-doc
protoc-gen-jrpc-doc is used to generate documentation from comments in your proto files.
 protoc-gen-jrpc-doc is used to generate documentation from comments in your proto files.
Package extensions implements a system for working with extended options.
 Package extensions implements a system for working with extended options.
envoyproxy_validate
google_api_http
lyft_validate
validator_field
tmp
googleapis/google/example/endpointsapis/goapp
The goapp command implements a simple App Engine app to demonstrate how to use the Service Control API v2 for admission control.
 The goapp command implements a simple App Engine app to demonstrate how to use the Service Control API v2 for admission control.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.