GeneratorsGo

Go configuration

View as Markdown

You can customize the behavior of the Go SDK generator in generators.yml:

generators.yml
1groups:
2  go-sdk:
3    generators:
4      - name: fernapi/fern-go-sdk
5        version: 1.40.0
6        config:
7          packageName: acme
8        output:
9          location: local-file-system
10          path: ../generated/go
alwaysSendRequiredProperties
booleanDefaults to true

When enabled, ensures that all required properties are always included in API requests, even if they have default values or are otherwise optional in the implementation.

clientConstructorName
string

Customizes the name of the client constructor function. This allows you to specify a custom name for the function that users will call to create a new instance of the client.

clientName
string

Specifies the name of the generated client struct. This determines the primary client type name that users will interact with in the generated Go SDK.

exportedClientName
string

Sets the name of the exported client that will be used in code snippets and documentation examples. This is useful for customizing how the client appears in generated documentation.

maxRetries
number

The default number of retries for failed requests. When not set, the generated SDK uses its own built-in default. SDK users can still override this per-request via request options.

offsetSemantics
'item-index' | 'page-index'

Controls how the offset parameter is interpreted for auto-paginated endpoints.

  • item-index: The offset counts individual items (e.g., offset 20 skips the first 20 items).
  • page-index: The offset counts pages (e.g., offset 3 skips to page 3).
omitFernHeaders
booleanDefaults to false

When enabled, the generated SDK omits the X-Fern-Language, X-Fern-SDK-Name, and X-Fern-SDK-Version headers from HTTP requests.

enableWireTests
booleanDefaults to true

Generates mock server (wire) tests to verify that the SDK sends the correct HTTP requests and correctly handles responses per the API spec. When enabled, Docker is required as a runtime dependency to run the generated tests.

importPath
string

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:

1default-group: local
2groups:
3  local:
4    generators:
5      - name: fernapi/fern-go-sdk
6        version: 0.13.0
7        config:
8          importPath: github.com/<YOUR_ORGANIZATION>/<YOUR_REPOSITORY>/generated/go
9        output:
10          location: local-file-system
11          path: ../generated/go
You must update the <YOUR_ORGANIZATION> and <YOUR_REPOSITORY> 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.
includeLegacyClientOptions
boolean

When enabled, includes legacy client options for backward compatibility with older versions of the SDK. This is useful for maintaining compatibility when upgrading SDK versions.

inlineFileProperties
booleanDefaults to true

Controls whether file upload properties are generated as inline request properties instead of separate parameters. When enabled, file upload fields become part of the request struct rather than being passed as individual function parameters.

inlinePathParameters
booleanDefaults to true

When enabled, path parameters are inlined into request types rather than being passed as separate function parameters. This creates a more unified request structure where path parameters are included in the request object.

module
object

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:

1default-group: local
2groups:
3  local:
4    generators:
5      - name: fernapi/fern-go-sdk
6        version: 0.13.0
7        config:
8          module:
9            path: github.com/<YOUR_ORGANIZATION>/<YOUR_REPOSITORY>
10        output:
11          location: local-file-system
12          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:

1default-group: local
2groups:
3  local:
4    generators:
5      - name: fernapi/fern-go-sdk
6        version: 0.13.0
7        config:
8          module:
9            path: github.com/<YOUR_ORGANIZATION>/<YOUR_REPOSITORY>
10            version: "1.19"
11        output:
12          location: local-file-system
13          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 statement:

1module github.com/your/module
2
3require "github.com/your/sdk" v0.0.0
4replace "github.com/your/sdk" v0.0.0 => "path/to/generated/sdk"
packageName
string

Specifies the package name for the generated Go code. This determines the package declaration that will appear at the top of generated Go files and affects how users import the SDK.

union
'v0' | 'v1'Defaults to v1

Controls the union type generation strategy. Use ‘v0’ for the legacy union implementation or ‘v1’ for the newer, more robust union handling approach that provides better type safety and discriminated union support.

useReaderForBytesRequest
booleanDefaults to true

When enabled, uses io.Reader interface for handling byte request bodies instead of byte slices. This is more memory-efficient for large payloads and follows Go best practices for streaming data.