Fix SDK config docs: correct field names, defaults, and add missing flags#5208
Fix SDK config docs: correct field names, defaults, and add missing flags#5208fern-support merged 2 commits intomainfrom
Conversation
…es, offsetSemantics, omitFernHeaders - Fix Python: lazy_import -> lazy_imports (wrong field name) - Fix Python: pyproject_python_version default ^3.8 -> ^3.10 - Fix Ruby: module -> moduleName (wrong field name) - Fix Go: enableWireTests type string -> boolean - Fix TS: generateSubpackageExports default false -> true - Add Go defaults: alwaysSendRequiredProperties, inlinePathParameters, inlineFileProperties, useReaderForBytesRequest (all true), union (v1) - Remove Go packageLayout (v1-only, not in v2) - Document maxRetries across all 9 language config pages - Document offsetSemantics for TS, Python, Java, Go, C#, PHP, Ruby - Document omitFernHeaders for TS, Python, Java, Go, C#, PHP, Ruby Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| <ParamField path="maxRetries" type="number" required={false} toc={true}> | ||
| 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. | ||
| </ParamField> |
There was a problem hiding this comment.
🔴 maxRetries uses camelCase in C# config where all other options use kebab-case
The C# configuration page uses kebab-case for every config key (base-api-exception-class-name, inline-path-parameters, offset-semantics, omit-fern-headers, etc. — 21 options total), but the newly added maxRetries on line 67 is the sole camelCase outlier. Notably, the other two options added in this same PR (offset-semantics at line 75 and omit-fern-headers at line 82) correctly use kebab-case, strongly suggesting maxRetries is a copy-paste error. If the generator expects max-retries, users following these docs will use the wrong key and the option will be silently ignored.
| <ParamField path="maxRetries" type="number" required={false} toc={true}> | |
| 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. | |
| </ParamField> | |
| <ParamField path="max-retries" type="number" required={false} toc={true}> | |
| 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. | |
| </ParamField> |
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
The casing is actually correct — the C# schema in CsharpConfigSchema.ts:119 defines the key as maxRetries (camelCase), not max-retries:
maxRetries: z.number().int().min(0).optional()This is the one key in the C# config that breaks the kebab-case convention — it was added more recently than the other options. The docs match the source of truth.
| <ParamField path="maxRetries" type="number" required={false} toc={true}> | ||
| 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. | ||
| </ParamField> |
There was a problem hiding this comment.
🔴 maxRetries uses camelCase instead of kebab-case in Java config, inconsistent with all other options
The Java generator configuration uses kebab-case for every other multi-word config option (e.g., base-api-exception-class-name, client-class-name, inline-path-parameters, enable-wire-tests, offset-semantics, omit-fern-headers, etc. — 27 options total at fern/products/sdks/generators/java/configuration.mdx). The newly added maxRetries is the sole camelCase option. The other two options added in this same PR (offset-semantics at line 97 and omit-fern-headers at line 104) correctly use kebab-case. If the documented key doesn't match what the generator actually expects, users will set a config value that is silently ignored, causing unexpected retry behavior.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
The casing is actually correct — the Java schema in BaseJavaCustomConfigSchema.ts:44 defines the key as maxRetries (camelCase):
maxRetries: z.number().int().min(0).optional()This key was added more recently and doesn't follow the kebab-case convention of the other Java config keys, but the docs need to match the actual schema.
Good catch on the alphabetical ordering though — fixed in dfce849.
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2 participants
Summary
Audit of all 9 SDK generator configuration pages against the source-of-truth config schemas in
fern-api/fern. Fixes incorrect field names, wrong defaults, wrong types, and adds three previously undocumented cross-generator flags.Bug fixes
lazy_import→lazy_imports(wrong field name — would cause Pydantic validation error)pyproject_python_versiondefault^3.8→^3.10(wrong default)module→moduleName(wrong field name for Ruby v2)enableWireTeststypestring→boolean(wrong type)generateSubpackageExportsdefaultfalse→true(wrong default)alwaysSendRequiredProperties(true),inlinePathParameters(true),inlineFileProperties(true),useReaderForBytesRequest(true),union("v1")packageLayout(Go v1-only option, does not exist in v2)New documentation
maxRetries— added to all 9 languages (TS, Python, Java, Go, C#, PHP, Ruby, Rust, Swift)offsetSemantics— added to Python, Java, Go, C#, PHP, Ruby (TS already had it)omitFernHeaders— added to Python, Java, Go, C#, PHP, Ruby (TS already had it)Review & Testing Checklist for Human
lazy_imports(plural) matches the actual Pydantic field name ingenerators/python/src/fern_python/generators/sdk/custom_config.pypyproject_python_versiondefault is indeed^3.10in latest generatormoduleNameis the correct config key for Ruby v2 (BaseRubyCustomConfigSchema.ts)maxRetries,offsetSemantics, andomitFernHeadersuse the correct casing per language (camelCase for Go/Ruby/PHP/TS, kebab-case for Java/C#, snake_case for Python)Notes
offsetSemanticsoromitFernHeadersin their schemas, so those flags were intentionally not added to those languages.maxRetriesdefaults to 3 when unset (hardcoded inClientConfigGenerator.ts); this is noted in the docs.default_max_retries(snake_case) as the config key, withmaxRetriesaccepted as an alias viaparse_obj.Link to Devin session: https://app.devin.ai/sessions/e2be987659314cca813d1c2488e156b1
Requested by: @Swimburger