diff --git a/fern/products/sdks/overview/go/configuration.mdx b/fern/products/sdks/overview/go/configuration.mdx index a1da91217..2424f316b 100644 --- a/fern/products/sdks/overview/go/configuration.mdx +++ b/fern/products/sdks/overview/go/configuration.mdx @@ -3,6 +3,174 @@ title: Go Configuration description: Configuration options for the Fern Go SDK. --- -Discover how to configure the Fern Go SDK for your project. +You can customize the behavior of the Go SDK generator in `generators.yml`: -This page is a WIP, please refer to our previous [documentation](https://buildwithfern.com/learn/sdks/reference/configuration). \ No newline at end of file +```yaml {7-8} +default-group: local +groups: + local: + generators: + - name: fernapi/fern-go-sdk + version: + config: + packageName: acme + output: + location: local-file-system + path: ../generated/go +``` + +## SDK Configuration Options + + +Use this option if you plan to distribute the generated Go SDK as a separate, published Go module. + +If you only plan to use the generated SDK within your own Go module, use the `importPath` configuration option instead. + +You can generate the Go SDK code into a separate module (defined with its own `go.mod`) +with the following `generators.yml` configuration: + +```yaml {7-9} +default-group: local +groups: + local: + generators: + - name: fernapi/fern-go-sdk + version: 0.13.0 + config: + module: + path: github.com// + output: + location: local-file-system + path: ../generated/go +``` + +This configuration will generate a `go.mod` alongside the rest of the Go SDK code at the target output +location. With this, `import` statements within the generated Go SDK are all resolved from the configured +module path. + +By default, the generated `go.mod` will be set to `1.13`. You can override this behavior by specifying +the `version` key: + +```yaml {10} +default-group: local +groups: + local: + generators: + - name: fernapi/fern-go-sdk + version: 0.13.0 + config: + module: + path: github.com// + version: "1.19" + output: + location: local-file-system + path: ../generated/go +``` + +If you want to depend on the generated Go SDK locally (without distributing it as a separate Go module), +and you use the `module` configuration option, you will need to modify your project's top-level `go.mod` to include a [`replace`](https://go.dev/doc/modules/gomod-ref#replace) statement: + +```go +module github.com/your/module + +require "github.com/your/sdk" v0.0.0 +replace "github.com/your/sdk" v0.0.0 => "path/to/generated/sdk" +``` + + + + + + + +Use this option if you plan to depend on the generated Go SDK from within your project, and **not** depend on it as a separate, published Go module. + +If you plan to to distribute the generated Go SDK as a separate, published Go module, use the `module` configuration option instead. + +You can generate the Go SDK code into a `gen/go/api` package with the following `generators.yml` +configuration: + +```yaml {7-8} +default-group: local +groups: + local: + generators: + - name: fernapi/fern-go-sdk + version: 0.13.0 + config: + importPath: github.com///generated/go + output: + location: local-file-system + path: ../generated/go +``` +You must update the `` and `` placeholders +with the relevant elements in your `go.mod` path. In this case, the generated Go SDK uses the same `go.mod` path used by the rest of your Go module. + + + + + + + + + + + + + +By default, it's impossible to send an explicit JSON `null` for optional parameters. `enableExplicitNull: true` opts in to generating a generic `Optional[T]` type that can be used to distinguish between a `nil` value (nothing is sent), a non-`nil` value (the value is sent), and an explicit null (a `null` value is sent). This is particularly useful for `PATCH` endpoints. + +The `Optional` and `Null` constructor functions will be included at the root of your module and can be +used like so: + +```go +client := acmeclient.NewClient() +updatedFoo, err := client.Foo.Update( + context.TODO(), + &acme.UpdateFooRequest{ + Name: acme.Optional("example"), + Tag: acme.Null[string](), + }, + // Serialized as {"name":"example","tag":null} +) +``` + +An example configuration: + +```yaml {7-8} +default-group: local +groups: + local: + generators: + - name: fernapi/fern-go-sdk + version: 0.13.0 + config: + enableExplicitNull: true + output: + location: local-file-system + path: ../generated/go +``` + +This feature requires generics, so the generated `go.mod` will be upgraded to `1.18` (as opposed to `1.13`). + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file