From 46012984727a90082992502acebfd783cad76495 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 14 Oct 2025 13:21:49 -0400 Subject: [PATCH 1/3] clarify protobuf spec setup, add generators reference page --- fern/products/api-def/api-def.yml | 2 ++ fern/products/api-def/grpc-pages/overview.mdx | 11 ++++---- .../reference/generators-reference.mdx | 8 ++++++ .../reference/generators-yml-reference.mdx | 26 +------------------ fern/snippets/grpc-specs.mdx | 24 +++++++++++++++++ 5 files changed, 40 insertions(+), 31 deletions(-) create mode 100644 fern/products/api-def/grpc-pages/reference/generators-reference.mdx create mode 100644 fern/snippets/grpc-specs.mdx diff --git a/fern/products/api-def/api-def.yml b/fern/products/api-def/api-def.yml index 5cd08e799..1e579e6c9 100644 --- a/fern/products/api-def/api-def.yml +++ b/fern/products/api-def/api-def.yml @@ -213,6 +213,8 @@ navigation: - page: Error handling path: ./grpc-pages/services/errors.mdx slug: errors + - page: generators.yml reference + path: ./grpc-pages/reference/generators-reference.mdx - section: Fern Definition collapsed: true slug: ferndef diff --git a/fern/products/api-def/grpc-pages/overview.mdx b/fern/products/api-def/grpc-pages/overview.mdx index b9a52d6c7..7cb0d1195 100644 --- a/fern/products/api-def/grpc-pages/overview.mdx +++ b/fern/products/api-def/grpc-pages/overview.mdx @@ -6,7 +6,7 @@ description: gRPC is a high-performance RPC framework that uses Protocol Buffers - Fern only supports gRPC SDK generation for .NET/C#. + Fern only supports gRPC SDK generation for .NET/C#. For other languages, protobuf specs can be used for documentation generation. gRPC is a modern, open-source, high-performance Remote Procedure Call (RPC) framework that can run in any environment. It uses Protocol Buffers (protobuf) as the interface definition language and supports multiple programming languages. @@ -202,20 +202,19 @@ fern/ ``` -Create a `generators.yml` file in your fern directory and add a reference to your gRPC proto files: +Create a `generators.yml` file in your fern directory and add a reference to your gRPC proto files. See [gRPC generators.yml reference](/api-definitions/grpc/generators-yml-reference) for complete configuration options. ```yaml title="generators.yml" # Your API definition api: specs: - proto: - root: ./proto - target: ./proto/user_service.proto - + root: ../user-service/proto # Must be specified up to where the package starts + target: ../user-service/proto/data/v1/user_service.proto # Omit to generate docs for entire root folder groups: external: generators: - # Your generator configurations here + # Your C# generator configuration here, if relevant ``` Your final directory structure: diff --git a/fern/products/api-def/grpc-pages/reference/generators-reference.mdx b/fern/products/api-def/grpc-pages/reference/generators-reference.mdx new file mode 100644 index 000000000..fd185f76c --- /dev/null +++ b/fern/products/api-def/grpc-pages/reference/generators-reference.mdx @@ -0,0 +1,8 @@ +--- +title: gRPC generators.yml reference +description: Reference for configuring gRPC specifications in your generators.yml file +--- + +Configure how your gRPC specification is processed and transformed into SDKs and documentation using the `generators.yml` configuration file. + + \ No newline at end of file diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index 5c07b7f48..7bfa46d98 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -226,31 +226,7 @@ api: - -```yaml title="generators.yml" -api: - specs: - - proto: - root: "./proto" - target: "proto/service/v1/service.proto" - local-generation: true -``` - - - Path to the `.proto` directory root (e.g., `proto`). - - - - Path to the target `.proto` file (e.g., `proto/user/v1/user.proto`). - - - - Path to the overrides configuration. - - - - Whether to compile `.proto` files locally. Defaults to remote generation (`false`). - + diff --git a/fern/snippets/grpc-specs.mdx b/fern/snippets/grpc-specs.mdx new file mode 100644 index 000000000..63a4bd8f5 --- /dev/null +++ b/fern/snippets/grpc-specs.mdx @@ -0,0 +1,24 @@ +```yaml title="generators.yml" +api: + specs: + - proto: + root: "./proto" + target: "proto/service/v1/service.proto" + local-generation: true +``` + + + Path to the `.proto` directory root (e.g., `proto`). 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/` + + + + Path to the target `.proto` file (e.g., `proto/user/v1/user.proto`). Omit to generate docs for the entire root folder. + + + + Path to the overrides configuration file. Used for SDK generation only, not for documentation generation. + + + + Whether to compile `.proto` files locally. Defaults to remote generation (`false`). + \ No newline at end of file From 94555d4884297cf734f4248e57ca3c97d9a1d1c6 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 14 Oct 2025 13:28:30 -0400 Subject: [PATCH 2/3] fix --- fern/products/api-def/grpc-pages/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/api-def/grpc-pages/overview.mdx b/fern/products/api-def/grpc-pages/overview.mdx index 7cb0d1195..17cf4e33a 100644 --- a/fern/products/api-def/grpc-pages/overview.mdx +++ b/fern/products/api-def/grpc-pages/overview.mdx @@ -209,7 +209,7 @@ Create a `generators.yml` file in your fern directory and add a reference to you api: specs: - proto: - root: ../user-service/proto # Must be specified up to where the package starts + root: ../user-service/proto # Path up to where package starts (e.g., for package userservice.v1) target: ../user-service/proto/data/v1/user_service.proto # Omit to generate docs for entire root folder groups: external: From c445a83e3317b094878078c3e39e591a21391370 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 14 Oct 2025 13:34:16 -0400 Subject: [PATCH 3/3] fix code comments and callout --- fern/products/api-def/grpc-pages/overview.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/fern/products/api-def/grpc-pages/overview.mdx b/fern/products/api-def/grpc-pages/overview.mdx index 17cf4e33a..c8abe0852 100644 --- a/fern/products/api-def/grpc-pages/overview.mdx +++ b/fern/products/api-def/grpc-pages/overview.mdx @@ -6,7 +6,7 @@ description: gRPC is a high-performance RPC framework that uses Protocol Buffers - Fern only supports gRPC SDK generation for .NET/C#. For other languages, protobuf specs can be used for documentation generation. + Fern only supports gRPC SDK generation for .NET/C#. Protobuf specs can be used for documentation generation in all languages. gRPC is a modern, open-source, high-performance Remote Procedure Call (RPC) framework that can run in any environment. It uses Protocol Buffers (protobuf) as the interface definition language and supports multiple programming languages. @@ -209,8 +209,10 @@ Create a `generators.yml` file in your fern directory and add a reference to you api: specs: - proto: - root: ../user-service/proto # Path up to where package starts (e.g., for package userservice.v1) - target: ../user-service/proto/data/v1/user_service.proto # Omit to generate docs for entire root folder + # Path up to where package starts (e.g., for package userservice.v1) + root: ../user-service/proto + # Omit to generate docs for entire root folder + target: ../user-service/proto/data/v1/user_service.proto groups: external: generators: