From 11eb01ae139008e16aad0754aa9bf63cb0f6a032 Mon Sep 17 00:00:00 2001 From: Kapil Gowru Date: Thu, 31 Jul 2025 15:27:37 -0600 Subject: [PATCH 1/2] Update parameter-names.mdx based on issue #266 --- .../pages/extensions/parameter-names.mdx | 76 ++++++++++++++++--- 1 file changed, 65 insertions(+), 11 deletions(-) diff --git a/fern/products/openapi-def/pages/extensions/parameter-names.mdx b/fern/products/openapi-def/pages/extensions/parameter-names.mdx index ff60bf613..cb277d2b0 100644 --- a/fern/products/openapi-def/pages/extensions/parameter-names.mdx +++ b/fern/products/openapi-def/pages/extensions/parameter-names.mdx @@ -1,16 +1,19 @@ --- title: Customize parameter names -description: Use `x-fern-parameter-name` to customize query parameter, header and path parameter naming. +description: Learn about all the available OpenAPI extensions in Fern to customize parameter naming and behavior. --- - 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 Fern generates SDKs from your OpenAPI spec. -## Headers +## Parameter Name Customization -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. +The `x-fern-parameter-name` extension allows you to customize the variable names of parameters in your generated SDKs, making them more readable and intuitive. + +### Headers + +In the example below, the header `X-API-Version` is renamed to `version` in the generated SDK for better readability: ```yaml {8} paths: @@ -26,10 +29,9 @@ paths: required: true ``` -## Query parameters +### 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. +Here, the query parameter `q` is renamed to `search_terms` to be more descriptive: ```yaml {8} paths: @@ -45,10 +47,9 @@ paths: required: false ``` -## Path parameters +### 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. +The path parameter `userId` is renamed to `id` to reduce verbosity: ```yaml {8} paths: @@ -63,3 +64,56 @@ paths: type: string required: false ``` + +## SDK Variables + +The `x-fern-sdk-variables` extension lets you define variables that can be reused across multiple endpoints in your API spec. This is particularly useful for common path parameters like `project_id` that appear in many routes. + +```yaml +components: + x-fern-sdk-variables: + project_id: + type: string + description: "The ID of the project" + pattern: "^proj_[a-zA-Z0-9]+$" + +paths: + "/v1/connect/{project_id}/accounts": + parameters: + - name: project_id + in: path + required: true + schema: + type: string + pattern: "^proj_[a-zA-Z0-9]+$" + x-fern-sdk-variable: "project_id" +``` + +When using this extension: + +- Define variables under `components.x-fern-sdk-variables` +- Reference them in path parameters using `x-fern-sdk-variable` +- The SDK client will accept these variables in the constructor +- Values are automatically injected into API requests + +This reduces repetition and makes your SDKs more maintainable, as users only need to provide values like `project_id` once during client initialization rather than passing them to every method call. + + + SDK variables are currently supported in Python SDKs from version 4.24.0 and higher. + + +## API URL Customization + +The `x-fern-api-url` extension allows you to customize the base URL for API requests in your generated SDKs: + +```yaml {3} +servers: + - url: "https://api.example.com" + x-fern-api-url: "api_url" +``` + +This renames the URL parameter to `api_url` in the SDK client constructor. + + + Use these extensions to create SDKs that are more intuitive and user-friendly while maintaining consistency with your API's underlying structure. + \ No newline at end of file From fa6a056a1e23578bfbf595d0436229b95e2ecbc2 Mon Sep 17 00:00:00 2001 From: Kapil Gowru Date: Thu, 31 Jul 2025 15:27:38 -0600 Subject: [PATCH 2/2] Update configuration.mdx based on issue #266 --- .../sdks/overview/python/configuration.mdx | 89 ++++++++++++------- 1 file changed, 57 insertions(+), 32 deletions(-) diff --git a/fern/products/sdks/overview/python/configuration.mdx b/fern/products/sdks/overview/python/configuration.mdx index 1c0eb6af7..b8fddb9cd 100644 --- a/fern/products/sdks/overview/python/configuration.mdx +++ b/fern/products/sdks/overview/python/configuration.mdx @@ -21,6 +21,7 @@ groups: ## SDK Configuration Options + Additional items to export in the package's __init__.py file. @@ -28,6 +29,7 @@ groups: + If true, excludes type definitions from being exported in the package's __init__.py file. @@ -40,12 +42,15 @@ groups: + Additional development dependencies to include in the generated SDK's pyproject.toml. + Optional dependency groups to define in pyproject.toml. + If true, generates a flatter file structure without nested directories. @@ -53,14 +58,15 @@ groups: - 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. - Whether or not to include legacy wire tests in the generated SDK + Whether or not to include legacy wire tests in the generated SDK. + When true, includes utility functions for working with union types. @@ -72,26 +78,18 @@ groups: - -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" + ``` + Configuration options for Pydantic model generation. @@ -112,18 +110,16 @@ groups: # Visit every case in the union shape = get_shape() shape.visit( - circle: lambda circle: do_something_with_circle(circle), - triangle: lambda triangle: do_something_with_triangle(triangle), + circle = lambda circle: do_something_with_circle(circle), + triangle = lambda triangle: do_something_with_triangle(triangle), ) ``` - - When enabled, the python generator will not run Black formatting in the generated code. Black is slow so this can potentially speed up code generation quite a bit. By default, the generator generates pydantic models that are v1 and v2 compatible. However you can override them to: - `v1`: strictly use Pydantic v1 - - `v2`: strictly use Pydantic v2 + - `v2`: strictly use Pydantic v2 - `both`: maintain compatibility with both versions - `v1_on_v2`: use Pydantic v1 compatibility layer on v2 @@ -140,6 +136,7 @@ groups: + Custom pyproject.toml content to include in the generated SDK. @@ -147,6 +144,7 @@ groups: + If true, skips code formatting of the generated SDK. @@ -154,6 +152,7 @@ groups: + When true, includes the API name in the generated package name. @@ -168,17 +167,43 @@ groups: 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. -### client - Configuration for the generated client class and file structure. +### Extension Headers - ```yaml - config: - client: - filename: "my_client.py" - class_name: "MyClient" - exported_filename: "my_client.py" - exported_class_name: "MyClient" - ``` +You can specify SDK variables using the `x-fern-sdk-variables` extension in your OpenAPI spec. These will be added as constructor parameters in the generated client: + +```yaml +components: + # ...other components +x-fern-sdk-variables: + project_id: + type: string + description: The ID of the project + pattern: "^proj_[a-zA-Z0-9]+$" +``` + +This will generate a client constructor that accepts the variable: + +```python +from my_sdk import Client + +client = Client( + project_id="proj_abc123" # Required variable from x-fern-sdk-variables +) +``` + +The SDK will automatically inject these variables into API paths that contain matching parameter names. + +### client +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" +``` The filename for the generated client file.