Skip to content

Commit 9f4f5db

Browse files
devalogdevalog
committed
Revamp file a bit more
1 parent 1a2fc20 commit 9f4f5db

File tree

1 file changed

+193
-46
lines changed

1 file changed

+193
-46
lines changed

‎fern/products/sdks/reference/generators-yml-reference.mdx‎

Lines changed: 193 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,6 @@ schema for `generators.yml`.
1010

1111
```yaml
1212
# Example generators.yml configuration
13-
auth-schemes:
14-
bearer:
15-
scheme: bearer
16-
token: "${API_TOKEN}"
17-
1813
api:
1914
specs:
2015
- openapi: "./openapi.yml"
@@ -64,120 +59,272 @@ groups:
6459
## auth-schemes
6560
Configures authentication methods for your API.
6661
62+
<ParamField path="auth-schemes" type="map<string, AuthSchemeDeclarationSchema>" required={false}>
63+
</ParamField>
64+
65+
## api
66+
67+
<ParamField path="api" type="APIConfigurationSchema">
68+
Defines the API specification (OpenAPI, AsyncAPI, etc.) and how to parse it.
69+
</ParamField>
70+
6771
```yaml
68-
auth-schemes:
69-
myAuth:
70-
# AuthSchemeDeclarationSchema properties would go here
72+
api:
73+
specs:
74+
- openapi: "./openapi.yml"
75+
namespace: "v1"
76+
settings:
77+
title-as-schema-name: true
78+
inline-path-parameters: false
7179
```
7280
73-
<ParamField path="auth-schemes" type="map<string, AuthSchemeDeclarationSchema>" required={false}>
81+
### General Configuration Options
82+
83+
```yaml
84+
api:
85+
specs:
86+
- openapi: "./openapi.yml"
87+
namespace: "v1"
88+
settings:
89+
title-as-schema-name: true
90+
inline-path-parameters: false
91+
- asyncapi: "./events.yml"
92+
namespace: "events"
93+
headers:
94+
Authorization: "Bearer ${API_TOKEN}"
95+
environments:
96+
production: "https://api.prod.com"
97+
staging: "https://api.staging.com"
98+
```
99+
100+
<ParamField path="api.specs" type="list<SpecSchema> | ConjureSchema" required={true}>
101+
List of API specifications or Conjure configuration.
74102
</ParamField>
75103
76-
## api
77-
Defines the API specification (OpenAPI, AsyncAPI, etc.) and how to parse it.
104+
<ParamField path="api.auth" type="ApiAuthSchema">
105+
Authentication configuration for the API.
106+
</ParamField>
107+
108+
<ParamField path="api.headers" type="map<string, string>">
109+
Default headers to include with API requests.
110+
</ParamField>
111+
112+
<ParamField path="api.environments" type="EnvironmentsSchema">
113+
Environment configurations for different deployment targets.
114+
</ParamField>
115+
116+
### Specification Types
117+
118+
#### OpenAPI
78119
79120
```yaml
80121
api:
81122
specs:
82123
- openapi: "./openapi.yml"
124+
origin: "https://api.example.com/openapi.json"
125+
overrides: "./openapi-overrides.yml"
83126
namespace: "v1"
84127
settings:
85128
title-as-schema-name: true
86129
inline-path-parameters: false
130+
prefer-undiscriminated-unions-with-literals: true
131+
filter:
132+
endpoints: ["POST /users", "GET /users/{id}"]
133+
example-generation:
134+
request:
135+
max-depth: 2
87136
```
88137
89-
<ParamField path="api" type="APIConfigurationSchema" required={false}>
138+
<ParamField path="specs[].openapi" type="string" required={true}>
139+
Path to the OpenAPI specification file.
90140
</ParamField>
91141
92-
<ParamField path="api.specs" type="list<SpecSchema>" required={false}>
142+
<ParamField path="specs[].origin" type="string">
143+
URL of the API definition origin for polling updates.
93144
</ParamField>
94145
95-
<ParamField path="api.specs[].openapi" type="string" required={true}>
146+
<ParamField path="specs[].overrides" type="string">
147+
Path to OpenAPI overrides file.
96148
</ParamField>
97149
98-
<ParamField path="api.specs[].origin" type="string" required={false}>
150+
<ParamField path="specs[].namespace" type="string">
151+
Namespace for the specification.
99152
</ParamField>
100153
101-
<ParamField path="api.specs[].overrides" type="string" required={false}>
154+
<ParamField path="specs[].settings" type="OpenAPISettingsSchema">
155+
OpenAPI-specific generation settings.
102156
</ParamField>
103157
104-
<ParamField path="api.specs[].namespace" type="string" required={false}>
158+
<ParamField path="settings.title-as-schema-name" type="boolean" default="true">
159+
Whether to use the titles of schemas within an OpenAPI definition as the names of types within Fern.
105160
</ParamField>
106161
107-
<ParamField path="api.specs[].settings" type="OpenAPISettingsSchema" required={false}>
162+
<ParamField path="settings.inline-path-parameters" type="boolean" default="false">
163+
Whether to include path parameters within the generated in-lined request.
108164
</ParamField>
109165
110-
<ParamField path="api.specs[].settings.respect-nullable-schemas" type="boolean" required={false}>
166+
<ParamField path="settings.prefer-undiscriminated-unions-with-literals" type="boolean" default="false">
167+
Whether to prefer undiscriminated unions with literals.
111168
</ParamField>
112169
113-
<ParamField path="api.specs[].settings.title-as-schema-name" type="boolean" default="true" required={false}>
170+
<ParamField path="settings.only-include-referenced-schemas" type="boolean" default="false">
171+
Whether to only include schemas referenced by endpoints in the generated SDK (tree-shaking).
114172
</ParamField>
115173
116-
<ParamField path="api.specs[].settings.optional-additional-properties" type="boolean" required={false}>
174+
<ParamField path="settings.respect-nullable-schemas" type="boolean" default="false">
175+
Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional.
117176
</ParamField>
118177
119-
<ParamField path="api.specs[].settings.coerce-enums-to-literals" type="boolean" required={false}>
178+
<ParamField path="settings.object-query-parameters" type="boolean">
179+
Enables parsing deep object query parameters.
120180
</ParamField>
121181
122-
<ParamField path="api.specs[].settings.idiomatic-request-names" type="boolean" required={false}>
182+
<ParamField path="settings.respect-readonly-schemas" type="boolean">
183+
Enables exploring readonly schemas in OpenAPI specifications.
123184
</ParamField>
124185
125-
<ParamField path="api.specs[].settings.only-include-referenced-schemas" type="boolean" default="false" required={false}>
186+
<ParamField path="settings.respect-forward-compatible-enums" type="boolean" default="false">
187+
Enables respecting forward compatible enums in OpenAPI specifications.
126188
</ParamField>
127189
128-
<ParamField path="api.specs[].settings.inline-path-parameters" type="boolean" default="false" required={false}>
190+
<ParamField path="settings.use-bytes-for-binary-response" type="boolean">
191+
Enables using the `bytes` type for binary responses. Defaults to file stream.
129192
</ParamField>
130193

131-
<ParamField path="api.specs[].settings.prefer-undiscriminated-unions-with-literals" type="boolean" default="false" required={false}>
194+
<ParamField path="settings.default-form-parameter-encoding" type="FormParameterEncoding" default="json">
195+
The default encoding of form parameters. Options: `form`, `json`.
132196
</ParamField>
133197

134-
<ParamField path="api.specs[].settings.object-query-parameters" type="boolean" required={false}>
198+
<ParamField path="settings.additional-properties-defaults-to" type="boolean" default="false">
199+
Configure what `additionalProperties` should default to when not explicitly defined on a schema.
135200
</ParamField>
136201

137-
<ParamField path="api.specs[].settings.respect-readonly-schemas" type="boolean" required={false}>
202+
<ParamField path="settings.type-dates-as-strings" type="boolean" default="true">
203+
If true, convert strings with format date to strings. If false, convert to dates.
138204
</ParamField>
139205

140-
<ParamField path="api.specs[].settings.respect-forward-compatible-enums" type="boolean" default="false" required={false}>
206+
<ParamField path="settings.preserve-single-schema-oneof" type="boolean" default="false">
207+
If true, preserve oneOf structures with a single schema. If false, unwrap them.
141208
</ParamField>
142209

143-
<ParamField path="api.specs[].settings.use-bytes-for-binary-response" type="boolean" required={false}>
210+
<ParamField path="settings.filter.endpoints" type="list<string>">
211+
Endpoints to include in the generated SDK (e.g., "POST /users").
144212
</ParamField>
145213

146-
<ParamField path="api.specs[].settings.default-form-parameter-encoding" type="'form' | 'json'" required={false}>
214+
<ParamField path="settings.example-generation.request.max-depth" type="integer">
215+
Controls the maximum depth for which optional properties will have examples generated. A depth of 0 means no optional properties will have examples.
147216
</ParamField>
148217

149-
<ParamField path="api.specs[].settings.additional-properties-defaults-to" type="boolean" default="false" required={false}>
218+
<ParamField path="settings.example-generation.response.max-depth" type="integer">
219+
Controls the maximum depth for which optional properties will have examples generated in responses.
150220
</ParamField>
151221

152-
<ParamField path="api.specs[].settings.type-dates-as-strings" type="boolean" default="true" required={false}>
222+
#### AsyncAPI
223+
224+
```yaml
225+
api:
226+
specs:
227+
- asyncapi: "./asyncapi.yml"
228+
origin: "https://api.example.com/asyncapi.json"
229+
overrides: "./asyncapi-overrides.yml"
230+
namespace: "events"
231+
settings:
232+
message-naming: "v2"
233+
title-as-schema-name: false
234+
respect-nullable-schemas: true
235+
```
236+
237+
<ParamField path="specs[].asyncapi" type="string" required={true}>
238+
Path to the AsyncAPI specification file.
239+
</ParamField>
240+
241+
<ParamField path="specs[].origin" type="string">
242+
URL of the API definition origin for polling updates.
243+
</ParamField>
244+
245+
<ParamField path="specs[].overrides" type="string">
246+
Path to AsyncAPI overrides file.
247+
</ParamField>
248+
249+
<ParamField path="specs[].namespace" type="string">
250+
Namespace for the specification.
153251
</ParamField>
154252

155-
<ParamField path="api.specs[].settings.preserve-single-schema-oneof" type="boolean" default="false" required={false}>
253+
<ParamField path="specs[].settings" type="AsyncAPISettingsSchema">
254+
AsyncAPI-specific generation settings.
156255
</ParamField>
157256

158-
<ParamField path="api.specs[].settings.filter" type="OpenAPIFilterSchema" required={false}>
257+
<ParamField path="settings.message-naming" type="MessageNamingSettingsSchema" default="v1">
258+
What version of message naming to use for AsyncAPI messages. Options: `v1`, `v2`.
159259
</ParamField>
160260

161-
<ParamField path="api.specs[].settings.filter.endpoints" type="string[]" required={false}>
261+
<ParamField path="settings.title-as-schema-name" type="boolean" default="true">
262+
Whether to use the titles of schemas within an AsyncAPI definition as the names of types within Fern.
162263
</ParamField>
163264

164-
<ParamField path="api.specs[].settings.example-generation" type="OpenAPIExampleGenerationSchema" required={false}>
265+
<ParamField path="settings.respect-nullable-schemas" type="boolean" default="false">
266+
Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional.
165267
</ParamField>
166268

167-
<ParamField path="api.specs[].settings.example-generation.request" type="RequestOrResponseExampleGenerationSchema" required={false}>
269+
#### Protocol Buffers
270+
271+
```yaml
272+
api:
273+
specs:
274+
- proto:
275+
root: "./proto"
276+
target: "proto/service/v1/service.proto"
277+
local-generation: true
278+
```
279+
280+
<ParamField path="specs[].proto" type="ProtobufDefinitionSchema" required={true}>
281+
Protocol Buffers configuration.
168282
</ParamField>
169283

170-
<ParamField path="api.specs[].settings.example-generation.request.max-depth" type="integer" required={false}>
284+
<ParamField path="specs[].proto.target" type="string">
285+
Path to the target `.proto` file (e.g., `proto/user/v1/user.proto`).
171286
</ParamField>
172287

173-
<ParamField path="api.specs[].settings.example-generation.response" type="RequestOrResponseExampleGenerationSchema" required={false}>
288+
<ParamField path="specs[].proto.root" type="string" required={true}>
289+
Path to the `.proto` directory root (e.g., `proto`).
174290
</ParamField>
175291

176-
<ParamField path="api.specs[].settings.example-generation.response.max-depth" type="integer" required={false}>
292+
<ParamField path="specs[].proto.overrides" type="string">
293+
Path to the overrides configuration.
294+
</ParamField>
295+
296+
<ParamField path="specs[].proto.local-generation" type="boolean">
297+
Whether to compile `.proto` files locally. Defaults to remote generation.
298+
</ParamField>
299+
300+
#### OpenRPC
301+
302+
<ParamField path="specs[].openrpc" type="string" required={true}>
303+
Path to the OpenRPC specification file.
304+
</ParamField>
305+
306+
<ParamField path="specs[].overrides" type="string">
307+
Path to OpenRPC overrides file.
308+
</ParamField>
309+
310+
<ParamField path="specs[].namespace" type="string">
311+
Namespace for the specification.
312+
</ParamField>
313+
314+
#### Conjure
315+
316+
```yaml
317+
api:
318+
specs:
319+
conjure: "./conjure-api.yml"
320+
```
321+
322+
<ParamField path="specs.conjure" type="string">
323+
Path to Conjure specification file.
177324
</ParamField>
178325

179326
## whitelabel
180-
Branding/publishing configuration (like GitHub credentials for publishing)
327+
Branding/publishing configuration (like GitHub credentials for publishing).
181328

182329
```yaml
183330
whitelabel:
@@ -203,7 +350,7 @@ whitelabel:
203350
</ParamField>
204351

205352
## metadata
206-
Package metadata like description and authors that gets included in generated SDKs
353+
Package metadata like description and authors that gets included in generated SDKs.
207354

208355
```yaml
209356
metadata:
@@ -231,7 +378,7 @@ metadata:
231378
</ParamField>
232379

233380
## readme
234-
Controls what goes into the generated README files across all SDKs
381+
Controls what goes into the generated README files across all SDKs.
235382

236383
```yaml
237384
readme:
@@ -282,7 +429,7 @@ readme:
282429
</ParamField>
283430

284431
## default-group
285-
Which group to use when none is specified
432+
Which group to use when none is specified.
286433

287434
```yaml
288435
default-group: "production"
@@ -582,7 +729,7 @@ groups:
582729
</ParamField>
583730

584731
## reviewers
585-
Who should review generated code
732+
Who should review generated code.
586733

587734
```yaml
588735
reviewers:

0 commit comments

Comments
 (0)