gRPC

gRPC generators.yml reference

View as Markdown

The generators.yml file serves two roles: it declares your gRPC specification location (in the api.specs section), and configures SDK generation (in the optional groups section).

APIs declared here can be rendered in your documentation via docs.yml. See Generate your API Reference.

generators.yml
1api:
2  specs:
3    - proto:
4        root: "./proto"
5        target: "proto/service/v1/service.proto"
6        local-generation: true
7    - proto:
8        root:
9          git:
10            repo: https://github.com/org/proto-definitions.git
11            ref: v2.3.0
12            path: proto/
13        target: user/v1/user.proto
root
string | gitRequired

Location of the .proto directory root. Accepts a local path (e.g., proto) or a remote git reference. Must be specified up to where the package starts. For example, if your package is package.test.v1 at the file path protos/package/test/v1/test_file.proto, the root should be protos/

1# Local path
2root: ./proto
3
4# Remote git repository
5root:
6  git:
7    repo: https://github.com/org/proto-definitions.git
8    ref: v2.3.0
9    path: proto/
root.git.repo
stringRequired

The git repository URL (e.g., https://github.com/org/repo.git). The CLI shallow-clones this repository at generation time using your system’s git credential configuration (credential helpers, SSH keys, GIT_ASKPASS).

root.git.ref
string

Branch, tag, or commit SHA to check out. Defaults to the repository’s default branch when omitted.

root.git.path
stringRequired

Path to the .proto directory within the repository.

target
string

Path to the target .proto file (e.g., proto/user/v1/user.proto). Omit to generate docs for the entire root folder.

overrides
string | list of strings

Path to the overrides configuration file, or a list of paths to multiple override files applied sequentially. Used for SDK generation only, not for documentation generation.

1# Single override file
2overrides: ./overrides.yml
3
4# Multiple override files (applied in order)
5overrides:
6  - ./base-overrides.yml
7  - ./sdk-overrides.yml
local-generation
booleanDefaults to false

Whether to compile .proto files locally. Defaults to remote generation (false). When enabled, you must have buf installed on your machine or in your CI/CD environment (e.g., GitHub Actions).