Documentation
¶
Overview ¶
Package openapi is the OpenAPI generator of the platform, the protoc-gen-platform-openapi plugin of buf. It describes the REST API the way the gateway of the api module serves it: proto field names, enums by name, 64-bit integers as strings, every field of a response present, requests checked by protovalidate, files over multipart/form-data, one error body. The human part of the description stays in the project's base.yaml.
Index ¶
- Constants
- func CheckDocuments(docs []DocumentSpec) error
- func CommentText(text string) string
- func DocumentFile(name string) string
- func Generate(req *pluginpb.CodeGeneratorRequest) (map[string][]byte, error)
- func IsFile(md protoreflect.MessageDescriptor) bool
- func Merge(base []byte, doc *Document) ([]byte, error)
- func RequestFor(param string, files ...protoreflect.FileDescriptor) *pluginpb.CodeGeneratorRequest
- func Run(in []byte) ([]byte, error)
- func Summary(text string) string
- type Components
- type Document
- type DocumentSpec
- type Encoding
- type Info
- type MediaType
- type Operation
- type Options
- type Ordered
- type Parameter
- type PathItem
- type RequestBody
- type Response
- type Schema
- type Selector
- type Tag
- type Value
Constants ¶
const ( LayoutSplit = "split" LayoutSingle = "single" )
The layouts of the output.
const ( // RootFile is the description people read and review: the base, the tags and a // reference to every path in the file of its proto file. RootFile = "openapi.yaml" // BundleFile is the whole description in one file without external references: // what the service serves and what clients are generated from. BundleFile = "openapi.bundle.yaml" // CommonFile holds what belongs to no described proto file: the error body and // the messages of dependencies such as googleapis. CommonFile = "common.yaml" )
The files of the split layout, relative to the output folder.
const AllDocuments = "all"
AllDocuments names the whole description among the documents: the api module's API_DOCS_DOCUMENTS lists it to serve /openapi.yaml, so no document may take the name.
const Header = "# Code generated by protoc-gen-platform-openapi. DO NOT EDIT.\n"
Header starts every file the generator writes.
Variables ¶
This section is empty.
Functions ¶
func CheckDocuments ¶
func CheckDocuments(docs []DocumentSpec) error
CheckDocuments finds what is wrong with the documents themselves, before any proto file is read: names, duplicates, empty entries.
func CommentText ¶
CommentText is a comment of a proto file as the generator reads it: the indentation its lines share and tool instructions removed.
func DocumentFile ¶
DocumentFile is the bundle of a document, relative to the output folder.
func Generate ¶
func Generate(req *pluginpb.CodeGeneratorRequest) (map[string][]byte, error)
Generate describes the services of the files to generate: file name to content.
func IsFile ¶
func IsFile(md protoreflect.MessageDescriptor) bool
IsFile reports whether a message is a file of a multipart request, the way the gateway fills it: content bytes, with a filename or a content type next to them.
func Merge ¶
Merge puts the generated document into the base one: the base keeps what it says — info, servers, security, the descriptions of tags, its own components — and the generator adds the tags it found, the paths and the schemas.
func RequestFor ¶
func RequestFor(param string, files ...protoreflect.FileDescriptor) *pluginpb.CodeGeneratorRequest
RequestFor is the request buf would send for files already compiled into the binary, their imports first: tests describe the proto files of their own packages with it. The descriptors of compiled files carry no comments.
Types ¶
type Components ¶
type Components struct {
Schemas *Ordered[*Schema] `yaml:"schemas,omitempty"`
Responses *Ordered[*Response] `yaml:"responses,omitempty"`
}
Components are the schemas and responses operations refer to.
type Document ¶
type Document struct {
OpenAPI string `yaml:"openapi"`
Info *Info `yaml:"info,omitempty"`
Tags []*Tag `yaml:"tags,omitempty"`
Paths *Ordered[*PathItem] `yaml:"paths,omitempty"`
Components *Components `yaml:"components,omitempty"`
Extensions map[string]any `yaml:",inline"`
}
Document is an OpenAPI 3.1 document.
func Describe ¶
func Describe(files []protoreflect.FileDescriptor) (*Document, error)
Describe builds the document of the services of the files.
type DocumentSpec ¶
type DocumentSpec struct {
Name string `yaml:"name"`
Title string `yaml:"title"` // info.title; the base's when empty
Description string `yaml:"description"` // info.description; the base's when empty
Include Selector `yaml:"include"` // what goes in; everything when empty
Exclude Selector `yaml:"exclude"` // what stays out of what goes in
}
DocumentSpec is a description for one audience — the tablet, the public, the admin panel — cut out of the whole one: api.openapi.documents in platformgo.yaml. The generator writes it as openapi.<name>.bundle.yaml, with only the operations it selects and only the components they use; the api module serves it at /openapi/<name>.yaml.
func ReadDocuments ¶
func ReadDocuments(file string) ([]DocumentSpec, error)
ReadDocuments reads api.openapi.documents of platformgo.yaml: the plugin gets the path of the file, documents=platformgo.yaml, and buf runs it in the project folder. platformgo checks the file against its schema; here only the documents matter.
type Encoding ¶
type Encoding struct {
ContentType string `yaml:"contentType,omitempty"`
}
Encoding is how a part of a multipart body is written.
type MediaType ¶
type MediaType struct {
Schema *Schema `yaml:"schema"`
Encoding *Ordered[*Encoding] `yaml:"encoding,omitempty"`
}
MediaType is the schema of a body in one content type.
type Operation ¶
type Operation struct {
Tags []string `yaml:"tags,omitempty"`
Summary string `yaml:"summary,omitempty"`
Description string `yaml:"description,omitempty"`
OperationID string `yaml:"operationId"`
Deprecated bool `yaml:"deprecated,omitempty"`
Parameters []*Parameter `yaml:"parameters,omitempty"`
RequestBody *RequestBody `yaml:"requestBody,omitempty"`
Responses *Ordered[*Response] `yaml:"responses"`
Extensions map[string]any `yaml:",inline"`
}
Operation is one HTTP binding of an RPC.
type Options ¶
type Options struct {
Base string // base=api/openapi/base.yaml: the human part, merged into the output
Layout string // layout=split (default): a file per proto file, the root and the bundle; single: one file
Path string // path=openapi.yaml: the file of the single layout, relative to out
// Documents is documents=platformgo.yaml: the file whose api.openapi.documents
// describe the documents for one audience each, openapi.<name>.bundle.yaml.
Documents string
}
Options are the parameters of the plugin, opt: in buf.gen.yaml.
func ParseOptions ¶
ParseOptions reads the parameter string of the plugin: key=value pairs separated by commas.
type Ordered ¶
type Ordered[V any] struct { // contains filtered or unexported fields }
Ordered is a map that keeps the order its keys were set in.
func (*Ordered[V]) MarshalYAML ¶
MarshalYAML writes the keys in order.
type Parameter ¶
type Parameter struct {
Name string `yaml:"name"`
In string `yaml:"in"`
Description string `yaml:"description,omitempty"`
Required bool `yaml:"required,omitempty"`
Deprecated bool `yaml:"deprecated,omitempty"`
Style string `yaml:"style,omitempty"`
Explode *bool `yaml:"explode,omitempty"`
Schema *Schema `yaml:"schema"`
}
Parameter is a path or query parameter.
type PathItem ¶
type PathItem struct {
Ref string `yaml:"$ref,omitempty"` // the item in the file of its proto file
Get *Operation `yaml:"get,omitempty"`
Put *Operation `yaml:"put,omitempty"`
Post *Operation `yaml:"post,omitempty"`
Delete *Operation `yaml:"delete,omitempty"`
Options *Operation `yaml:"options,omitempty"`
Head *Operation `yaml:"head,omitempty"`
Patch *Operation `yaml:"patch,omitempty"`
Trace *Operation `yaml:"trace,omitempty"`
}
PathItem holds the operations of one path.
type RequestBody ¶
type RequestBody struct {
Description string `yaml:"description,omitempty"`
Required bool `yaml:"required,omitempty"`
Content *Ordered[*MediaType] `yaml:"content"`
}
RequestBody is the body of a call.
type Response ¶
type Response struct {
Ref string `yaml:"$ref,omitempty"`
Description string `yaml:"description,omitempty"`
Content *Ordered[*MediaType] `yaml:"content,omitempty"`
}
Response is an answer of an operation, or a reference to a shared one.
type Schema ¶
type Schema struct {
Ref string `yaml:"$ref,omitempty"`
Type any `yaml:"type,omitempty"` // a name, or a list of names for a nullable type
Format string `yaml:"format,omitempty"`
Description string `yaml:"description,omitempty"`
Deprecated bool `yaml:"deprecated,omitempty"`
Const *Value `yaml:"const,omitempty"`
Enum []any `yaml:"enum,omitempty"`
Pattern string `yaml:"pattern,omitempty"`
MinLength *uint64 `yaml:"minLength,omitempty"`
MaxLength *uint64 `yaml:"maxLength,omitempty"`
Minimum *Value `yaml:"minimum,omitempty"`
ExclusiveMinimum *Value `yaml:"exclusiveMinimum,omitempty"`
Maximum *Value `yaml:"maximum,omitempty"`
ExclusiveMaximum *Value `yaml:"exclusiveMaximum,omitempty"`
ContentEncoding string `yaml:"contentEncoding,omitempty"`
ContentMediaType string `yaml:"contentMediaType,omitempty"`
Items *Schema `yaml:"items,omitempty"`
MinItems *uint64 `yaml:"minItems,omitempty"`
MaxItems *uint64 `yaml:"maxItems,omitempty"`
UniqueItems bool `yaml:"uniqueItems,omitempty"`
Properties *Ordered[*Schema] `yaml:"properties,omitempty"`
Required []string `yaml:"required,omitempty"`
AdditionalProperties *Value `yaml:"additionalProperties,omitempty"` // false or a *Schema
PropertyNames *Schema `yaml:"propertyNames,omitempty"`
MinProperties *uint64 `yaml:"minProperties,omitempty"`
MaxProperties *uint64 `yaml:"maxProperties,omitempty"`
OneOf []*Schema `yaml:"oneOf,omitempty"`
AnyOf []*Schema `yaml:"anyOf,omitempty"`
AllOf []*Schema `yaml:"allOf,omitempty"`
Not *Schema `yaml:"not,omitempty"`
Examples []any `yaml:"examples,omitempty"`
Extensions map[string]any `yaml:",inline"`
}
Schema is a JSON Schema 2020-12 schema, the subset the generator writes.
type Selector ¶
type Selector struct {
TagGroups []string `yaml:"tag_groups"`
Tags []string `yaml:"tags"`
Services []string `yaml:"services"`
}
Selector picks operations: one matches when its tag is listed, its tag is in a listed group of x-tagGroups, or the gRPC service of its method is listed by full name.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package convert moves the openapiv2 options of grpc-gateway (protoc-gen-openapiv2) in proto files to what the platform's OpenAPI generator reads: descriptions into proto comments, examples, tags and hidden methods into platform.openapi.v1 options, the file-level openapiv2_swagger into api/openapi/base.yaml.
|
Package convert moves the openapiv2 options of grpc-gateway (protoc-gen-openapiv2) in proto files to what the platform's OpenAPI generator reads: descriptions into proto comments, examples, tags and hidden methods into platform.openapi.v1 options, the file-level openapiv2_swagger into api/openapi/base.yaml. |
|
Package oascheck validates OpenAPI 3.1 documents and values against their schemas, for the tests of the generator and of the api module: a document must pass the schema of the specification, every schema in it must compile as JSON Schema 2020-12, and what the gateway answers must match the schema the document gives for it.
|
Package oascheck validates OpenAPI 3.1 documents and values against their schemas, for the tests of the generator and of the api module: a document must pass the schema of the specification, every schema in it must compile as JSON Schema 2020-12, and what the gateway answers must match the schema the document gives for it. |