# Protobuf and gRPC elements

Source: https://apigenie.pl/docs/reference/doc-components/protobuf
Part of the reference of [@mykulyak/apigenie-docs](https://apigenie.pl/docs/reference/doc-components.md).
Its other pages: [apg-api-reference and apg-spec](https://apigenie.pl/docs/reference/doc-components/reference-and-spec.md), [OpenAPI elements](https://apigenie.pl/docs/reference/doc-components/openapi.md), [Swagger 2.0 elements](https://apigenie.pl/docs/reference/doc-components/swagger.md), [AsyncAPI elements](https://apigenie.pl/docs/reference/doc-components/asyncapi.md), [GraphQL elements](https://apigenie.pl/docs/reference/doc-components/graphql.md), [Building blocks](https://apigenie.pl/docs/reference/doc-components/building-blocks.md), [Try it out](https://apigenie.pl/docs/reference/doc-components/try-it-out.md), [Theming](https://apigenie.pl/docs/reference/doc-components/theming.md), [Server-side rendering](https://apigenie.pl/docs/reference/doc-components/server-side-rendering.md), [apigenie-docs build](https://apigenie.pl/docs/reference/doc-components/docs-build.md).

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.

```html
<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](/docs/reference/doc-components#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-markdown>`](/docs/reference/doc-components/building-blocks#apg-markdown): `markdown`

## `<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](/docs/reference/doc-components#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-markdown>`](/docs/reference/doc-components/building-blocks#apg-markdown): `markdown`
- [`<apg-method-badge>`](/docs/reference/doc-components/building-blocks#apg-method-badge): `method`

## `<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](/docs/reference/doc-components#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-markdown>`](/docs/reference/doc-components/building-blocks#apg-markdown): `markdown`
- [`<apg-protobuf-message>`](/docs/reference/doc-components/protobuf#apg-protobuf-message): `message`, `full-name`, `fields`, `field`, `type-link`, `options`, `method-link`
- [`<apg-code-block>`](/docs/reference/doc-components/building-blocks#apg-code-block): `code-block`, `code`, `copy-button`
- [`<apg-grpc-code-samples>`](/docs/reference/doc-components/protobuf#apg-grpc-code-samples): `code-samples`, `tab`, `tab-active`

## `<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](/docs/reference/doc-components#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-markdown>`](/docs/reference/doc-components/building-blocks#apg-markdown): `markdown`
- [`<apg-code-block>`](/docs/reference/doc-components/building-blocks#apg-code-block): `code-block`, `code`, `copy-button`
- [`<apg-method-badge>`](/docs/reference/doc-components/building-blocks#apg-method-badge): `method`

## `<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](/docs/reference/doc-components#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-markdown>`](/docs/reference/doc-components/building-blocks#apg-markdown): `markdown`

## `<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](/docs/reference/doc-components#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:

- [`<apg-code-block>`](/docs/reference/doc-components/building-blocks#apg-code-block): `code-block`, `code`, `copy-button`