From 4cf2d9c16187919c13006b66d01ff776ff0ad52b Mon Sep 17 00:00:00 2001 From: Yuki Hirasawa <48427044+hirasawayuki@users.noreply.github.com> Date: Wed, 19 Jun 2024 06:47:30 +0900 Subject: [PATCH] docs: update documentation to use buf.gen.yaml v2 (#162) The Buf CLI 1.32.0 introduced a v2 config format for buf.gen.yaml ([blog post](https://buf.build/blog/buf-cli-next-generation)). This PR updates the examples in documentation to use buf.gen.yaml v2 for generating code. --------- Signed-off-by: hirasawayuki Signed-off-by: Nick Snyder Signed-off-by: Philip K. Warren Co-authored-by: Nick Snyder Co-authored-by: Philip K. Warren Signed-off-by: Steve Ayers --- docs/go/getting-started.md | 12 +-- docs/kotlin/generating-code.md | 12 +-- docs/kotlin/getting-started.md | 75 +++++++++------- docs/node/getting-started.md | 60 +++++++++---- docs/swift/generating-code.md | 28 +++--- docs/swift/getting-started.md | 85 ++++++++++--------- docs/swift/testing.md | 15 ++-- docs/web/generating-code.mdx | 19 ++--- .../web/supported-browsers-and-frameworks.mdx | 12 +-- 9 files changed, 176 insertions(+), 142 deletions(-) diff --git a/docs/go/getting-started.md b/docs/go/getting-started.md index 80242c3e..d960b075 100644 --- a/docs/go/getting-started.md +++ b/docs/go/getting-started.md @@ -89,17 +89,17 @@ configuration files to get going. (If you'd prefer, you can skip this section and use `protoc` instead — `protoc-gen-connect-go` behaves like any other plugin.) -First, scaffold a basic [`buf.yaml`][buf.yaml] by running `buf mod init`. Next, +First, scaffold a basic [`buf.yaml`][buf.yaml] by running `buf config init`. Next, tell Buf how to generate code by putting this into [`buf.gen.yaml`][buf.gen.yaml]: ```yaml -version: v1 +version: v2 plugins: - - plugin: go + - local: protoc-gen-go out: gen opt: paths=source_relative - - plugin: connect-go + - local: protoc-gen-connect-go out: gen opt: paths=source_relative ``` @@ -333,8 +333,8 @@ query parameters. More importantly, your users got an idiomatic, type-safe client without *any* extra work on your part. [buf]: https://buf.build/ -[buf.gen.yaml]: https://buf.build/docs/configuration/v1/buf-gen-yaml -[buf.yaml]: https://buf.build/docs/configuration/v1/buf-yaml +[buf.gen.yaml]: https://buf.build/docs/configuration/v2/buf-gen-yaml +[buf.yaml]: https://buf.build/docs/configuration/v2/buf-yaml [buf-cli]: https://github.com/bufbuild/buf [cURL]: https://curl.se/ [godoc]: https://pkg.go.dev/connectrpc.com/connect diff --git a/docs/kotlin/generating-code.md b/docs/kotlin/generating-code.md index 9e5d63fd..d329c3da 100644 --- a/docs/kotlin/generating-code.md +++ b/docs/kotlin/generating-code.md @@ -64,7 +64,7 @@ When developing a new project, 2 new files need to be created: The first file, `buf.yaml`, can be created by running: ```bash -buf mod init +buf config init ``` The second file, `buf.gen.yaml`, needs to be created manually and specifies @@ -72,11 +72,11 @@ which plugins should be used to generate code. An example of this file is shown below: ```yaml -version: v1 +version: v2 plugins: - - plugin: buf.build/connectrpc/kotlin + - remote: buf.build/connectrpc/kotlin out: generated - - plugin: buf.build/protocolbuffers/java + - remote: buf.build/protocolbuffers/java out: generated ``` @@ -156,8 +156,8 @@ The following generation options can be combined in the `opt` field of the `buf. [available-plugins]: https://buf.build/plugins [buf]: https://buf.build/docs/ -[buf.gen.yaml]: https://buf.build/docs/configuration/v1/buf-gen-yaml -[buf.yaml]: https://buf.build/docs/configuration/v1/buf-yaml +[buf.gen.yaml]: https://buf.build/docs/configuration/v2/buf-gen-yaml +[buf.yaml]: https://buf.build/docs/configuration/v2/buf-yaml [buf-cli]: https://buf.build/docs/installation [connect-kotlin]: https://github.com/connectrpc/connect-kotlin [connect-kotlin-plugin]: https://buf.build/connectrpc/kotlin diff --git a/docs/kotlin/getting-started.md b/docs/kotlin/getting-started.md index d3795a6d..03758bd3 100644 --- a/docs/kotlin/getting-started.md +++ b/docs/kotlin/getting-started.md @@ -50,38 +50,32 @@ is not overridden, the rest of the example will need to replace `com.example.eli Create an Android application with Gradle and Android Studio. Now we can start defining a new API for talking with Eliza! -## Define a Protobuf service +## Define a service -In the shell, create a proto directory to keep the `.proto` files in. +First, we need to add a Protobuf file that includes our service definition. For this tutorial, we are going to construct a unary endpoint for a service that is a stripped-down implementation of ELIZA, the famous natural language processing program. ```bash -$ mkdir proto -$ cd proto +$ mkdir -p proto && touch proto/eliza.proto ``` -Next, scaffold a basic [`buf.yaml`][buf.yaml] by running `buf mod init`. +Open up the above file and add the following service definition: -```bash -$ buf mod init -``` +```proto +syntax = "proto3"; -We have already defined the `ElizaService` and have -it [hosted on the Buf Schema Registry][eliza-proto] to use in this example. -Export the Protobuf schema to use in our project. +package connectrpc.eliza.v1; -```bash title="~/.../Eliza/proto" -$ buf export buf.build/connectrpc/eliza -o . -``` +message SayRequest { + string sentence = 1; +} -Our new `proto` directory should look like this: +message SayResponse { + string sentence = 1; +} -``` -proto -├── connectrpc -│ └── eliza -│ └── v1 -│ └── eliza.proto -└── buf.yaml +service ElizaService { + rpc Say(SayRequest) returns (SayResponse) {} +} ``` Open the newly created `eliza.proto` file in the editor. @@ -98,20 +92,36 @@ are the input and output for the `Say` RPC method. We're going to generate our code using [`buf`][buf], a modern replacement for Google's protobuf compiler. -```bash -$ cd .. -$ touch buf.gen.yaml +First, scaffold a basic [`buf.yaml`][buf.yaml] by running `buf config init` at the root of your repository. Then, edit `buf.yaml` +to use our `proto` directory: + +```yaml title=buf.yaml +version: v2 +// highlight-next-line +modules: +// highlight-next-line + - path: proto +lint: + use: + - DEFAULT +breaking: + use: + - FILE ``` We will use [_remote plugins_][remote-plugins], a feature of the [Buf Schema Registry][bsr] for generating code. Tell `buf` -how to generate code by putting this into [`buf.gen.yaml`][buf.gen.yaml]: +how to generate code by creating a [`buf.gen.yaml`][buf.gen.yaml]: + +```bash +$ touch buf.gen.yaml +``` ```yaml title=buf.gen.yaml -version: v1 +version: v2 plugins: - - plugin: buf.build/protocolbuffers/java + - remote: buf.build/protocolbuffers/java out: app/src/main/java - - plugin: buf.build/connectrpc/kotlin + - remote: buf.build/connectrpc/kotlin out: app/src/main/java ``` @@ -134,7 +144,8 @@ With those configuration files in place, generating Kotlin code can be easily done: ```bash -$ buf generate proto +$ buf lint +$ buf generate ``` In the `app/src/main/java` directory, there should now be some generated Java and Kotlin files: @@ -668,9 +679,9 @@ the Connect-Kotlin repository on GitHub. These examples demonstrate: [buf-cli]: https://buf.build/docs/installation -[buf.gen.yaml]: https://buf.build/docs/configuration/v1/buf-gen-yaml +[buf.gen.yaml]: https://buf.build/docs/configuration/v2/buf-gen-yaml -[buf.yaml]: https://buf.build/docs/configuration/v1/buf-yaml +[buf.yaml]: https://buf.build/docs/configuration/v2/buf-yaml [connect-go]: https://github.com/connectrpc/connect-go diff --git a/docs/node/getting-started.md b/docs/node/getting-started.md index 4825633d..e25b81d7 100644 --- a/docs/node/getting-started.md +++ b/docs/node/getting-started.md @@ -39,10 +39,7 @@ $ npm install @bufbuild/buf @bufbuild/protoc-gen-es @bufbuild/protobuf @connectr ## Define a service -First, we need to add a Protobuf file that includes our service definition. For -this tutorial, we are going to construct a unary endpoint for a service that is -a stripped-down implementation of [ELIZA](https://en.wikipedia.org/wiki/ELIZA), -the famous natural language processing program. +First, we need to add a Protobuf file that includes our service definition. For this tutorial, we are going to construct a unary endpoint for a service that is a stripped-down implementation of ELIZA, the famous natural language processing program. ```bash $ mkdir -p proto && touch proto/eliza.proto @@ -50,7 +47,7 @@ $ mkdir -p proto && touch proto/eliza.proto Open up the above file and add the following service definition: -```protobuf +```proto syntax = "proto3"; package connectrpc.eliza.v1; @@ -76,24 +73,49 @@ but we also need a configuration file to get going. (If you'd prefer, you can skip this section and use `protoc` instead — `protoc-gen-connect-es` behaves like any other plugin.) -First, tell Buf how to generate code with a `buf.gen.yaml` file: +First, scaffold a basic [`buf.yaml`][buf.yaml] at the root of your repository: + +```bash +$ npx buf config init +``` + +Then, edit `buf.yaml` to use our `proto` directory: + +```yaml title=buf.yaml +version: v2 +// highlight-next-line +modules: +// highlight-next-line + - path: proto +lint: + use: + - DEFAULT +breaking: + use: + - FILE +``` + + +Next, tell Buf how to generate code by putting this into +[`buf.gen.yaml`][buf.gen.yaml]: ```yaml -version: v1 +version: v2 plugins: - - plugin: es - opt: target=ts + - local: protoc-gen-es out: gen - - plugin: connect-es opt: target=ts + - local: protoc-gen-connect-es out: gen + opt: target=ts ``` -With this file in place, you can generate code from the schema in the `proto` -directory: +With those configuration files in place, you can lint your schema and generate +code: ```bash -$ npx buf generate proto +$ npx buf lint +$ npx buf generate ``` You should now see two generated TypeScript files: @@ -101,17 +123,18 @@ You should now see two generated TypeScript files: ```diff . ├── buf.gen.yaml +├── buf.yaml // highlight-next-line ├── gen // highlight-next-line -│   ├── eliza_connect.ts +│ ├── eliza_connect.ts // highlight-next-line -│   └── eliza_pb.ts +│ └── eliza_pb.ts ├── node_modules ├── package-lock.json ├── package.json ├── proto -│   └── eliza.proto +│ └── eliza.proto └── tsconfig.json ``` @@ -351,3 +374,8 @@ supports both the gRPC and Connect protocols. Unlike a hand-written REST service you didn't need to design a URL hierarchy, hand-write request and response objects, or parse typed values out of query parameters. More importantly, your users got an idiomatic, type-safe client without any extra work on your part. + +[buf]: https://www.npmjs.com/package/@bufbuild/buf +[buf.gen.yaml]: https://buf.build/docs/configuration/v2/buf-gen-yaml +[buf.yaml]: https://buf.build/docs/configuration/v2/buf-yaml +[eliza-proto]: https://buf.build/connectrpc/eliza/file/main:connectrpc/eliza/v1/eliza.proto diff --git a/docs/swift/generating-code.md b/docs/swift/generating-code.md index d165400f..c63378e3 100644 --- a/docs/swift/generating-code.md +++ b/docs/swift/generating-code.md @@ -64,7 +64,7 @@ When developing a new project, 2 new files need to be created: The first file, `buf.yaml`, can be created by running: ```bash -buf mod init +buf config init ``` The second file, `buf.gen.yaml`, needs to be created manually and specifies @@ -72,18 +72,17 @@ which plugins should be used to generate code. An example of this file is shown below: ```yaml -version: v1 +version: v2 plugins: - - plugin: buf.build/connectrpc/swift + - remote: buf.build/connectrpc/swift + out: Generated opt: - GenerateAsyncMethods=true - GenerateCallbackMethods=true - Visibility=Public + - remote: buf.build/apple/swift out: Generated - - plugin: buf.build/apple/swift - opt: - - Visibility=Public - out: Generated + opt: Visibility=Public ``` This file specifies that the [`connect-swift` plugin][connect-swift-plugin] @@ -135,18 +134,17 @@ local generation, except the `buf.gen.yaml` file should be modified to use local plugins instead of remote plugins: ```yaml -version: v1 +version: v2 plugins: - - plugin: connect-swift # protoc-gen-connect-swift in your PATH + - local: protoc-gen-connect-swift # protoc-gen-connect-swift in your PATH + out: Generated opt: - GenerateAsyncMethods=true - GenerateCallbackMethods=true - Visibility=Public + - local: protoc-gen-swift # protoc-gen-swift in your PATH out: Generated - - plugin: swift # protoc-gen-swift in your PATH - opt: - - Visibility=Public - out: Generated + opt: Visibility=Public ``` ## Using generated code @@ -187,8 +185,8 @@ the `buf.gen.yaml` file as shown in the example above. [available-plugins]: https://buf.build/plugins [buf]: https://buf.build/docs/ -[buf.gen.yaml]: https://buf.build/docs/configuration/v1/buf-gen-yaml -[buf.yaml]: https://buf.build/docs/configuration/v1/buf-yaml +[buf.gen.yaml]: https://buf.build/docs/configuration/v2/buf-gen-yaml +[buf.yaml]: https://buf.build/docs/configuration/v2/buf-yaml [buf-cli]: https://buf.build/docs/installation [connect-swift]: https://github.com/connectrpc/connect-swift [connect-swift-mocks-plugin]: https://buf.build/connectrpc/swift-mocks diff --git a/docs/swift/getting-started.md b/docs/swift/getting-started.md index cc19b31a..4a23bd80 100644 --- a/docs/swift/getting-started.md +++ b/docs/swift/getting-started.md @@ -29,38 +29,41 @@ to generate a Connect-Swift client. This tutorial should take ~10 minutes from start to finish. -## Define a Protobuf service +## Prerequisites -We'll start by creating a Protobuf schema that defines the ELIZA -API. In your shell, create a `.proto` file: +* [The Buf CLI][buf-cli] installed, and include it in the `$PATH`. + +## Define a service + +First, we need to add a Protobuf file that includes our service definition. For this tutorial, we are going to construct a unary endpoint for a service that is a stripped-down implementation of ELIZA, the famous natural language processing program. ```bash -touch eliza.proto +$ mkdir -p proto && touch proto/eliza.proto ``` -Open the newly created `eliza.proto` file in your editor and add: +Open up the above file and add the following service definition: -```protobuf +```proto syntax = "proto3"; package connectrpc.eliza.v1; message SayRequest { - string sentence = 1; + string sentence = 1; } message SayResponse { - string sentence = 1; + string sentence = 1; } service ElizaService { - rpc Say(SayRequest) returns (SayResponse) {} + rpc Say(SayRequest) returns (SayResponse) {} } ``` +Open the newly created `eliza.proto` file in the editor. This file declares a `connectrpc.eliza.v1` Protobuf package, -a service called `ElizaService`, and a single unary -(single-request / single-response) method +a service called `ElizaService`, and a single method called `Say`. Under the hood, these components will be used to form the path of the API's HTTP URL. @@ -70,49 +73,48 @@ are the input and output for the `Say` RPC method. ## Generate code We're going to generate our code using [Buf][buf], a modern replacement for -Google's protobuf compiler. Specifically, we will use -[_remote plugins_][remote-plugins], -a feature of the Buf Schema Registry. This requires installing -[Buf's CLI][buf-cli]: - -```bash -brew install bufbuild/buf/buf -``` - -To configure Buf, scaffold a basic [`buf.yaml`][buf.yaml] by running: - -```bash -buf mod init +Google's protobuf compiler. We installed Buf earlier, but we also need a few +configuration files to get going. + +First, scaffold a basic [`buf.yaml`][buf.yaml] by running `buf config init` at the root of your repository. Then, edit `buf.yaml` +to use our `proto` directory: + +```yaml title=buf.yaml +version: v2 +// highlight-next-line +modules: +// highlight-next-line + - path: proto +lint: + use: + - DEFAULT +breaking: + use: + - FILE ``` -Next, tell Buf how to generate code by creating a new -[`buf.gen.yaml`][buf.gen.yaml] file: - -```bash -touch buf.gen.yaml -``` - -...and adding this content to it: +Next, tell Buf how to generate code by putting this into +[`buf.gen.yaml`][buf.gen.yaml]: ```yaml -version: v1 +version: v2 plugins: - - plugin: buf.build/connectrpc/swift + - remote: buf.build/connectrpc/swift + out: Generated opt: - GenerateAsyncMethods=true - GenerateCallbackMethods=true - Visibility=Public + - remote: buf.build/apple/swift out: Generated - - plugin: buf.build/apple/swift - opt: - - Visibility=Public - out: Generated + opt: Visibility=Public ``` With those configuration files in place, we can now generate code: ```bash -buf generate +$ buf lint +$ buf generate ``` In your `Generated` directory, you should now see some generated Swift files: @@ -494,10 +496,11 @@ enabling you to use Connect-Swift without the SwiftNIO dependency. [buf]: https://buf.build/docs/ [buf-cli]: https://buf.build/docs/installation -[buf.gen.yaml]: https://buf.build/docs/configuration/v1/buf-gen-yaml -[buf.yaml]: https://buf.build/docs/configuration/v1/buf-yaml +[buf.gen.yaml]: https://buf.build/docs/configuration/v2/buf-gen-yaml +[buf.yaml]: https://buf.build/docs/configuration/v2/buf-yaml [connect-go]: https://github.com/connectrpc/connect-go [connect-swift]: https://github.com/connectrpc/connect-swift +[eliza-proto]: https://buf.build/connectrpc/eliza/file/main:connectrpc/eliza/v1/eliza.proto [envoy-grpc-bridge]: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/connect_grpc_bridge_filter [go-demo]: https://github.com/connectrpc/examples-go [grpc]: https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md diff --git a/docs/swift/testing.md b/docs/swift/testing.md index 74a0450d..1b6d474b 100644 --- a/docs/swift/testing.md +++ b/docs/swift/testing.md @@ -17,27 +17,26 @@ interfaces and implementations into the `Generated` folder, and a corresponding set of mocks into the `GeneratedMocks` folder: ```yaml -version: v1 +version: v2 plugins: # Generated models - - plugin: buf.build/apple/swift - opt: - - Visibility=Public + - remote: buf.build/apple/swift out: Generated + opt: Visibility=Public # Production generated services/methods - - plugin: buf.build/connectrpc/swift + - remote: buf.build/connectrpc/swift + out: Generated opt: - GenerateAsyncMethods=true - GenerateCallbackMethods=true - Visibility=Public - out: Generated # Mock generated services/methods - - plugin: buf.build/connectrpc/swift-mocks + - remote: buf.build/connectrpc/swift-mocks + out: GeneratedMocks opt: - GenerateAsyncMethods=true - GenerateCallbackMethods=true - Visibility=Public - out: GeneratedMocks ``` **The `GenerateAsyncMethods` and diff --git a/docs/web/generating-code.mdx b/docs/web/generating-code.mdx index a29e64a3..e24e5c49 100644 --- a/docs/web/generating-code.mdx +++ b/docs/web/generating-code.mdx @@ -77,25 +77,20 @@ Next, tell Buf to use the two plugins with a new configuration file: ```yaml title="buf.gen.yaml" # buf.gen.yaml defines a local generation template. -# For details, see https://buf.build/docs/configuration/v1/buf-gen-yaml -version: v1 +# For details, see https://buf.build/docs/configuration/v2/buf-gen-yaml +version: v2 plugins: # This will invoke protoc-gen-es and write output to src/gen - - plugin: es + - local: protoc-gen-es out: src/gen - opt: - # Add more plugin options here - - target=ts + opt: target=ts # This will invoke protoc-gen-connect-es - - plugin: connect-es + - local: protoc-gen-connect-es out: src/gen - opt: - # Add more plugin options here - - target=ts + # Add more plugin options here + opt: target=ts ``` - - If desired, you can also skip local plugin installation and use [remote plugins](https://buf.build/docs/bsr/remote-plugins/overview). See the [connect-es example](https://buf.build/docs/bsr/remote-plugins/usage#connect-web) for a buf.gen.yaml which uses remote plugins. diff --git a/docs/web/supported-browsers-and-frameworks.mdx b/docs/web/supported-browsers-and-frameworks.mdx index 23e4c783..569550cf 100644 --- a/docs/web/supported-browsers-and-frameworks.mdx +++ b/docs/web/supported-browsers-and-frameworks.mdx @@ -63,15 +63,15 @@ the Protobuf-ES plugin and the Connect-ES plugin. For example, in your `buf.gen.yaml`: -```diff -version: v1 +```yaml +version: v2 plugins: - - plugin: es + - local: protoc-gen-es out: gen -+ opt: import_extension=none - - plugin: connect-es + opt: import_extension=none + - local: protoc-gen-connect-es out: gen -+ opt: import_extension=none + opt: import_extension=none ``` **Output JavaScript files**