openapi

package
v0.10.0 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

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

View Source
const (
	LayoutSplit  = "split"
	LayoutSingle = "single"
)

The layouts of the output.

View Source
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.

View Source
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.

View Source
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

func CommentText(text string) string

CommentText is a comment of a proto file as the generator reads it: the indentation its lines share and tool instructions removed.

func DocumentFile

func DocumentFile(name string) string

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

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

func Merge(base []byte, doc *Document) ([]byte, error)

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.

func Run

func Run(in []byte) ([]byte, error)

Run is the plugin: a CodeGeneratorRequest in, a CodeGeneratorResponse out. An error of the generator goes into the response, as protoc expects.

func Summary

func Summary(text string) string

Summary is the summary of a method the generator takes from its comment, empty when the comment has none it can use and the generator falls back to the method name.

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 Info

type Info struct {
	Title   string `yaml:"title"`
	Version string `yaml:"version"`
}

Info is the title and the version of the API.

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

func ParseOptions(param string) (Options, error)

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 NewOrdered

func NewOrdered[V any]() *Ordered[V]

NewOrdered returns an empty ordered map.

func (*Ordered[V]) IsZero

func (o *Ordered[V]) IsZero() bool

IsZero leaves an empty map out of the document.

func (*Ordered[V]) Len

func (o *Ordered[V]) Len() int

Len is the number of keys.

func (*Ordered[V]) MarshalYAML

func (o *Ordered[V]) MarshalYAML() (any, error)

MarshalYAML writes the keys in order.

func (*Ordered[V]) Set

func (o *Ordered[V]) Set(k string, v V)

Set sets a key; a new key goes last.

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.

type Tag

type Tag struct {
	Name        string         `yaml:"name"`
	Description string         `yaml:"description,omitempty"`
	Extensions  map[string]any `yaml:",inline"`
}

Tag is a section of the API.

type Value

type Value struct{ V any }

Value is a value that must be written even when it is the zero value: minimum: 0, const: false, additionalProperties: false.

func (Value) MarshalYAML

func (v Value) MarshalYAML() (any, error)

MarshalYAML writes the value itself.

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.

Jump to

Keyboard shortcuts

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