Protobuf and gRPC elements

The elements of Protobuf files with gRPC services. <apg-api-reference> and <apg-nav> pick them by themselves. Declarations are named by full name (acme.library.v1.Book) or by name relative to the package (Book.Author, LibraryService.GetBook).

.proto text is read by the protobuf WebAssembly module (protobuf.web.mjs and protobuf.web.wasm): give its URL with protobuf-wasm-url on <apg-spec> or <apg-api-reference>, or to every element with configureProtobufEngine(url). One file is documented: imports of the standard files (google/protobuf, google/api, google/rpc, grpc) are resolved, and the types of other imports are shown unresolved. The documentation model the module writes ({"apigenieProtobuf": 1, …}) can be given instead of the text and needs no module; server-side rendering embeds it in the page.

<apg-spec spec-url="/protos/library.proto" protobuf-wasm-url="/wasm/protobuf.web.mjs">
	<apg-protobuf-overview></apg-protobuf-overview>
	<apg-protobuf-method name="LibraryService.GetBook" target="api.example.com:443"></apg-protobuf-method>
	<apg-protobuf-message name="Book"></apg-protobuf-message>
</apg-spec>

<apg-protobuf-overview>

The package, file, syntax, header comment, imports and file options of a Protobuf file.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-protobuf-overview";.

Attributes

Attribute Property Type Default Description
heading-level headingLevel number 1 Level of the title heading (1–6).

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

CSS parts

Part Description
overview The container.
title The package (h1 unless heading-level says otherwise).
version Badges: the package version and the syntax.
info The file line.
section Sections (imports, options).
section-title Section headings.
options The list of file options.

Forwarded from the elements inside it:

<apg-protobuf-service>

A gRPC service of a Protobuf file: its description, options and methods, each with its streaming kind, request and response.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-protobuf-service";.

Attributes

Attribute Property Type Default Description
name name string The service, by full name (acme.v1.Library) or by name (Library).
heading-level headingLevel number 2 Level of the title heading.

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

CSS parts

Part Description
service The container.
header The header with the name and badges.
title The name.
full-name The full name.
badge Badges (deprecated).
section Sections (methods, options).
section-title Section headings.
method-link Links to the methods.
type-link Links to message pages.
options Lists of options.

Forwarded from the elements inside it:

<apg-protobuf-method>

A gRPC method: its streaming kind, HTTP/2 path, request and response messages (with their fields), HTTP/JSON transcoding rules (google.api.http), JSON examples of both messages and code samples.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-protobuf-method";.

Attributes

Attribute Property Type Default Description
name name string The method, by full name (acme.v1.Library.GetBook) or as Service.Method.
heading-level headingLevel number 2 Level of the title heading.
target target string The server the code samples call, host:port.
hide-samples hideSamples boolean false Hide the code samples.
lazy lazy boolean false Render only the header until the method comes near the viewport (used for long pages; the full content is always rendered on the server).

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

Methods

Method Description
reveal() Renders the full content of a lazy method.

CSS parts

Part Description
method The container.
header The header with the name and badges.
title The name.
summary The summary line, when the method has no description of its own.
grpc-path The HTTP/2 path of calls.
service-link The link to the service.
badge Badges (deprecated, idempotency).
section Sections (request, response, HTTP, examples, code samples).
section-title Section headings.
http-rules The table of HTTP transcoding rules.

Forwarded from the elements inside it:

<apg-protobuf-message>

A message of a Protobuf file: its fields (number, name and JSON name, type, label, oneof, options, comment), oneofs, reserved numbers and names, nested types, the methods using it and an example in the proto3 JSON form.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-protobuf-message";.

Attributes

Attribute Property Type Default Description
name name string The message, by full name (acme.v1.Book) or by name relative to the package (Book.Author).
heading-level headingLevel number 2 Level of the title heading.
embedded embedded boolean false Shown inside a method: the table of fields only.

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

CSS parts

Part Description
message The container.
header The header with the name and badges.
title The name.
full-name The full name.
badge Badges (deprecated).
section Sections (fields, oneofs, nested types…).
section-title Section headings.
fields The table of fields.
field A field’s row.
type-link Links to message and enum pages.
options Lists of options.
method-link Links to the methods using the message.

Forwarded from the elements inside it:

<apg-protobuf-enum>

An enum of a Protobuf file: its values (name, number, comment, deprecation), reserved numbers and names, and options. In JSON, values are written by name.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-protobuf-enum";.

Attributes

Attribute Property Type Default Description
name name string The enum, by full name (acme.v1.Genre) or by name relative to the package (Book.Author.Role).
heading-level headingLevel number 2 Level of the title heading.

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

CSS parts

Part Description
enum The container.
header The header with the name and badges.
title The name.
full-name The full name.
badge Badges (deprecated).
section Sections (values, reserved, options).
section-title Section headings.
values The table of values.
value A value’s row.
options Lists of options.

Forwarded from the elements inside it:

<apg-grpc-code-samples>

Code samples calling a gRPC method with its example request: grpcurl, Node.js (@grpc/grpc-js), Python (grpcio) and Go, in the form each takes for the method’s streaming kind. The Python and Go samples use the code protoc generates for the file.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-grpc-code-samples";.

Attributes

Attribute Property Type Default Description
method method string The method, by full name (acme.v1.Library.GetBook) or as Service.Method.
target target string The server the samples call, host:port (localhost:50051 by default).
languages languages string "grpcurl,node,python,go" Comma-separated languages: grpcurl, node, python, go.

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

CSS parts

Part Description
code-samples The container.
tab Language tabs; the selected one also has tab-active.
tab-active The selected tab.

Forwarded from the elements inside it:

Last updated on Edit this page on GitHubView as Markdown
Was this helpful?