Skip to content

Commit 20fb6db

Browse files
devalogdevalog
committed
Add content to Go config page
1 parent 10b6978 commit 20fb6db

File tree

1 file changed

+170
-2
lines changed

1 file changed

+170
-2
lines changed

‎fern/products/sdks/overview/go/configuration.mdx‎

Lines changed: 170 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,174 @@ title: Go Configuration
33
description: Configuration options for the Fern Go SDK.
44
---
55

6-
# Go Configuration
6+
You can customize the behavior of the Go SDK generator in `generators.yml`:
77

8-
Discover how to configure the Fern Go SDK for your project.
8+
```yaml {7-8}
9+
default-group: local
10+
groups:
11+
local:
12+
generators:
13+
- name: fernapi/fern-go-sdk
14+
version: <Markdown src="/snippets/version-number.mdx"/>
15+
config:
16+
packageName: acme
17+
output:
18+
location: local-file-system
19+
path: ../generated/go
20+
```
21+
22+
## SDK Configuration Options
23+
24+
<ParamField path="module" type="ModuleConfigSchema" required={false}>
25+
Use this option if you plan to distribute the generated Go SDK as a separate, published Go module.
26+
27+
<Note>If you only plan to use the generated SDK within your own Go module, use the `importPath` configuration option instead.</Note>
28+
29+
You can generate the Go SDK code into a separate module (defined with its own `go.mod`)
30+
with the following `generators.yml` configuration:
31+
32+
```yaml {7-9}
33+
default-group: local
34+
groups:
35+
local:
36+
generators:
37+
- name: fernapi/fern-go-sdk
38+
version: 0.13.0
39+
config:
40+
module:
41+
path: github.com/<YOUR_ORGANIZATION>/<YOUR_REPOSITORY>
42+
output:
43+
location: local-file-system
44+
path: ../generated/go
45+
```
46+
47+
This configuration will generate a `go.mod` alongside the rest of the Go SDK code at the target output
48+
location. With this, `import` statements within the generated Go SDK are all resolved from the configured
49+
module path.
50+
51+
By default, the generated `go.mod` will be set to `1.13`. You can override this behavior by specifying
52+
the `version` key:
53+
54+
```yaml {10}
55+
default-group: local
56+
groups:
57+
local:
58+
generators:
59+
- name: fernapi/fern-go-sdk
60+
version: 0.13.0
61+
config:
62+
module:
63+
path: github.com/<YOUR_ORGANIZATION>/<YOUR_REPOSITORY>
64+
version: "1.19"
65+
output:
66+
location: local-file-system
67+
path: ../generated/go
68+
```
69+
70+
If you want to depend on the generated Go SDK locally (without distributing it as a separate Go module),
71+
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:
72+
73+
```go
74+
module github.com/your/module
75+
76+
require "github.com/your/sdk" v0.0.0
77+
replace "github.com/your/sdk" v0.0.0 => "path/to/generated/sdk"
78+
```
79+
80+
</ParamField>
81+
82+
<ParamField path="packageName" type="string" required={false}>
83+
</ParamField>
84+
85+
<ParamField path="importPath" type="string" required={false}>
86+
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.
87+
88+
<Note>If you plan to to distribute the generated Go SDK as a separate, published Go module, use the `module` configuration option instead.</Note>
89+
90+
You can generate the Go SDK code into a `gen/go/api` package with the following `generators.yml`
91+
configuration:
92+
93+
```yaml {7-8}
94+
default-group: local
95+
groups:
96+
local:
97+
generators:
98+
- name: fernapi/fern-go-sdk
99+
version: 0.13.0
100+
config:
101+
importPath: github.com/<YOUR_ORGANIZATION>/<YOUR_REPOSITORY>/generated/go
102+
output:
103+
location: local-file-system
104+
path: ../generated/go
105+
```
106+
<Info>You must update the `<YOUR_ORGANIZATION>` and `<YOUR_REPOSITORY>` placeholders
107+
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.</Info>
108+
109+
</ParamField>
110+
111+
<ParamField path="alwaysSendRequiredProperties" type="boolean" required={false}>
112+
</ParamField>
113+
114+
<ParamField path="clientConstructorName" type="string" required={false}>
115+
</ParamField>
116+
117+
<ParamField path="clientName" type="string" required={false}>
118+
</ParamField>
119+
120+
<ParamField path="enableExplicitNull" type="boolean" required={false}>
121+
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.
122+
123+
The `Optional` and `Null` constructor functions will be included at the root of your module and can be
124+
used like so:
125+
126+
```go
127+
client := acmeclient.NewClient()
128+
updatedFoo, err := client.Foo.Update(
129+
context.TODO(),
130+
&acme.UpdateFooRequest{
131+
Name: acme.Optional("example"),
132+
Tag: acme.Null[string](),
133+
},
134+
// Serialized as {"name":"example","tag":null}
135+
)
136+
```
137+
138+
An example configuration:
139+
140+
```yaml {7-8}
141+
default-group: local
142+
groups:
143+
local:
144+
generators:
145+
- name: fernapi/fern-go-sdk
146+
version: 0.13.0
147+
config:
148+
enableExplicitNull: true
149+
output:
150+
location: local-file-system
151+
path: ../generated/go
152+
```
153+
154+
<Note>This feature requires generics, so the generated `go.mod` will be upgraded to `1.18` (as opposed to `1.13`).</Note>
155+
</ParamField>
156+
157+
<ParamField path="exportedClientName" type="string" required={false}>
158+
</ParamField>
159+
160+
<ParamField path="includeLegacyClientOptions" type="boolean" required={false}>
161+
</ParamField>
162+
163+
<ParamField path="inlinePathParameters" type="boolean" required={false}>
164+
</ParamField>
165+
166+
<ParamField path="inlineFileProperties" type="boolean" required={false}>
167+
</ParamField>
168+
169+
<ParamField path="packageLayout" type="'flat' | 'nested'" required={false}>
170+
</ParamField>
171+
172+
<ParamField path="union" type="'v0' | 'v1'" required={false}>
173+
</ParamField>
174+
175+
<ParamField path="useReaderForBytesRequest" type="boolean" required={false}>
176+
</ParamField>

0 commit comments

Comments
 (0)