Skip to content

🌿 Fern Scribe: Add a comprehensive list of all extension headers... #303

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

🌿 Fern Scribe: Add a comprehensive list of all extension headers... #303

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1be1921
Update parameter-names.mdx based on issue #266
kgowru Aug 1, 2025
04c20ac
Update configuration.mdx based on issue #266
kgowru Aug 1, 2025
e7ef518
Update configuration.mdx based on issue #266
kgowru Aug 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 73 additions & 19 deletions fern/products/openapi-def/pages/extensions/parameter-names.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,41 +1,55 @@
---
title: Customize parameter names
description: Use `x-fern-parameter-name` to customize query parameter, header and path parameter naming.
description: Use extensions to customize parameter naming in your generated SDKs.
---

<Note>
The `x-fern-parameter-name` extension allows you to customize the variable names of parameters in your generated SDKs.
Extensions allow you to customize how parameters are named and handled in your generated SDKs to improve readability and usability.
</Note>

## Headers
## Header Extensions

In the example below, the header `X-API-Version` is renamed to `version` in the
generated SDK. The rename makes the SDK more human readable.
### x-fern-parameter-name
Renames a header parameter in the generated SDK for better readability.

```yaml {8}
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

removed highlighting? Not sure why, highlighting would be useful for this.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The original text had an explanation of what the example was doing. Retaining the specific explanation or even moving it to a comment in the code block would be better. I like that fern scribe added a general definition of the extension, though.

```yaml
paths:
"/user":
get:
operationId: list_user
parameters:
- in: header
name: X-API-Version
name: X-API-Version
x-fern-parameter-name: version
schema:
type: string
required: true
```

## Query parameters

In the example below, the query parameter `q` is renamed to `search_terms` in the
generated SDK. The rename makes the parameter more approachable for end users.
### x-fern-sdk-header
Marks a header to be provided in the SDK client constructor rather than per-request.

```yaml {8}
paths:
"/user":
get:
parameters:
- in: header
name: X-API-Key
schema:
x-fern-sdk-header: api_key
type: string
required: true
```

## Query Parameter Extensions

### x-fern-parameter-name
Renames a query parameter in the generated SDK to be more descriptive.

```yaml
paths:
"/user/search":
get:
operationId: search_user
parameters:
- in: query
name: q
Expand All @@ -45,21 +59,61 @@ paths:
required: false
```

## Path parameters

In the example below, the path parameter `userId` is renamed to `id` in the
generated SDK. The rename makes the SDK less verbose.
### x-fern-sdk-variable
Marks a query parameter to be provided in the SDK client constructor.

```yaml {8}
paths:
"/user/search":
get:
parameters:
- in: query
name: org_id
schema:
x-fern-sdk-variable: organization_id
type: string
required: true
```

## Path Parameter Extensions

### x-fern-parameter-name
Renames a path parameter in the generated SDK for conciseness.

```yaml
paths:
"/user/{userId}":
get:
operationId: get_user
parameters:
- in: path
name: userId
x-fern-parameter-name: id
schema:
type: string
required: false
required: true
```

### x-fern-sdk-variable
Marks a path parameter to be provided in the SDK client constructor. This is useful for values that are common across many endpoints.

```yaml
paths:
"/projects/{project_id}/users":
get:
parameters:
- in: path
name: project_id
schema:
x-fern-sdk-variable: project_id
type: string
pattern: "^proj_[a-zA-Z0-9]+$"
required: true
```

<Note>
When using `x-fern-sdk-variable` or `x-fern-sdk-header`, the specified value will be provided once in the client constructor rather than needing to be passed to each individual API call.
</Note>

<Tip>
Use these extensions strategically to create a more ergonomic SDK. Consider renaming cryptic parameter names to be more descriptive, and moving commonly used values like API keys or project IDs to the client constructor.
</Tip>
105 changes: 59 additions & 46 deletions fern/products/sdks/overview/python/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,55 @@ groups:
## SDK Configuration Options

<ParamField path="additional_init_exports" type="array" default="null" required={false} toc={true}>
Additional exports to include in the package's __init__.py file.
</ParamField>

<ParamField path="client" type="object" default="{}" required={false} toc={true}>
Configuration for the generated client class and file structure.

```yaml
config:
client:
filename: "my_client.py"
class_name: "MyClient"
exported_filename: "my_client.py"
exported_class_name: "MyClient"
```
</ParamField>

<ParamField path="client.filename" type="string" default="client.py" required={false} toc={true}>
The filename for the generated client file.
</ParamField>

<ParamField path="client.class_name" type="string" default="null" required={false} toc={true}>
The name of the generated client class.
</ParamField>

<ParamField path="client.exported_filename" type="string" default="client.py" required={false} toc={true}>
The filename of the exported client which will be used in code snippets.
</ParamField>

<ParamField path="client.exported_class_name" type="string" default="null" required={false} toc={true}>
The name of the exported client class that will be used in code snippets.
</ParamField>

<ParamField path="default_bytes_stream_chunk_size" type="number" default="null" required={false} toc={true}>
The chunk size to use (if any) when processing a response bytes stream within `iter_bytes` or `aiter_bytes` results in: `for chunk in response.iter_bytes(chunk_size=<default_bytes_stream_chunk_size>):`
</ParamField>

<ParamField path="exclude_types_from_init_exports" type="bool" default="false" required={false} toc={true}>
Whether to exclude type definitions from the package's __init__.py exports.
</ParamField>

<ParamField path="extension_headers" type="object" default="{}" required={false} toc={true}>
Headers to inject into all requests made by the client. Useful for custom authentication or tracking.

```yaml
config:
extension_headers:
x-custom-header: "custom-value"
x-api-key: "default-key"
```
</ParamField>

<ParamField path="extra_dependencies" type="object" default="{}" required={false} toc={true}>
Expand All @@ -40,27 +82,31 @@ groups:
</ParamField>

<ParamField path="extra_dev_dependencies" type="object" default="{}" required={false} toc={true}>
Additional development dependencies to include in the generated package.
</ParamField>

<ParamField path="extras" type="object" default="{}" required={false} toc={true}>
Optional feature groups that can be installed with the package.
</ParamField>

<ParamField path="flat_layout" type="bool" default="false" required={false} toc={true}>
Whether to generate a flat file structure instead of nested directories.
</ParamField>

<ParamField path="follow_redirects_by_default" type="bool" default="true" required={false} toc={true}>
Whether to follow redirects by default in HTTP requests.
</ParamField>

<ParamField path="improved_imports" type="bool" default="true" required={false} toc={true}>
Feature flag that improves imports in the Python SDK by removing nested `resources` directory
Feature flag that improves imports in the Python SDK by removing nested `resources` directory.
</ParamField>

<ParamField path="include_legacy_wire_tests" type="bool" default="false" required={false} toc={true}>
Whether or not to include legacy wire tests in the generated SDK
Whether or not to include legacy wire tests in the generated SDK.
</ParamField>

<ParamField path="include_union_utils" type="bool" default="false" required={false} toc={true}>
Whether to include utility functions for working with union types.
</ParamField>

<ParamField path="inline_path_params" type="bool" default="false" required={false} toc={true}>
Expand All @@ -72,26 +118,18 @@ groups:
</ParamField>

<ParamField path="package_name" type="string" default="null" required={false} toc={true}>

Specifies the Python package name that users will import your generated client
from.
Specifies the Python package name that users will import your generated client from.

For example, setting `package_name: "my_custom_package"` enables users to use
`my_custom_package import Client` to import your client:
For example, setting `package_name: "my_custom_package"` enables users to use `from my_custom_package import Client` to import your client:

```yaml {7-10}
default-group: local
groups:
local:
generators:
- name: fernapi/fern-python
version: 0.7.1
config:
package_name: "my_custom_package"
```
```yaml
config:
package_name: "my_custom_package"
```
</ParamField>

<ParamField path="pydantic_config" type="SdkPydanticModelCustomConfig" default="SdkPydanticModelCustomConfig()" required={false} toc={true}>
<ParamField path="pydantic_config" type="object" default="{}" required={false} toc={true}>
Configuration options for Pydantic model generation.
</ParamField>

<ParamField path="pydantic_config.include_union_utils" type="bool" default="false" required={false} toc={true}>
Expand Down Expand Up @@ -140,20 +178,23 @@ groups:
</ParamField>

<ParamField path="pyproject_toml" type="string" default="null" required={false} toc={true}>
Custom pyproject.toml content to include in the generated package.
</ParamField>

<ParamField path="should_generate_websocket_clients" type="bool" default="false" required={false} toc={true}>
Feature flag that enables generation of Python websocket clients.
</ParamField>

<ParamField path="skip_formatting" type="bool" default="false" required={false} toc={true}>
Whether to skip code formatting of the generated files.
</ParamField>

<ParamField path="timeout_in_seconds" type="number | 'infinity'" default="60" required={false} toc={true}>
By default, the generator generates a client that times out after 60 seconds. You can customize this value by providing a different number or setting to `infinity` to get rid of timeouts.
</ParamField>

<ParamField path="use_api_name_in_package" type="bool" default="false" required={false} toc={true}>
Whether to include the API name in the generated package name.
</ParamField>

<ParamField path="use_inheritance_for_extended_models" type="bool" default="true" required={false} toc={true}>
Expand All @@ -166,32 +207,4 @@ groups:

<ParamField path="use_typeddict_requests_for_file_upload" type="bool" default="false" required={false} toc={true}>
Whether or not to generate TypedDicts instead of Pydantic Models for file upload request objects. Note that this flag was only introduced due to an oversight in the `use_typeddict_requests` flag implementation; it should be removed in the future.
</ParamField>

### client
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fern scribe removed this separate section. I think the document/more reasable is better with the separate section.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also kind of a weird change because the client params aren't directly related to the extension headers afaik?

Configuration for the generated client class and file structure.

```yaml
config:
client:
filename: "my_client.py"
class_name: "MyClient"
exported_filename: "my_client.py"
exported_class_name: "MyClient"
```

<ParamField path="filename" type="string" default="client.py" required={false} toc={true}>
The filename for the generated client file.
</ParamField>

<ParamField path="class_name" type="string" default="null" required={false} toc={true}>
The name of the generated client class.
</ParamField>

<ParamField path="exported_filename" type="string" default="client.py" required={false} toc={true}>
The filename of the exported client which will be used in code snippets.
</ParamField>

<ParamField path="exported_class_name" type="string" default="null" required={false} toc={true}>
The name of the exported client class that will be used in code snippets.
</ParamField>
Loading