diff --git a/fern/products/openapi-def/pages/extensions/parameter-names.mdx b/fern/products/openapi-def/pages/extensions/parameter-names.mdx index ff60bf613..f65bf021a 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. +title: Customize parameter and variable names +description: Use `x-fern` extensions to customize parameter and variable naming in your generated SDKs. --- - The `x-fern-parameter-name` extension allows you to customize the variable names of parameters in your generated SDKs. + Fern provides extensions to customize how parameters and variables are named in your generated SDKs, making them more intuitive for end users. -## Headers +## Parameter Names with x-fern-parameter-name -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 how parameters appear in your SDK. + +### 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. +This example renames the path parameter `userId` to `id` for conciseness: ```yaml {8} paths: @@ -63,3 +64,49 @@ paths: type: string required: false ``` + +## SDK Variables with x-fern-sdk-variables + +The `x-fern-sdk-variables` extension allows you to define variables that can be set once during SDK initialization and automatically injected into requests. This is useful for values that are common across multiple endpoints. + +```yaml +components: + # Other components... + +x-fern-sdk-variables: + project_id: + type: string + description: "The ID of the project" + pattern: "^proj_[a-zA-Z0-9]+$" +``` + +To use the variable in a path: + +```yaml +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 +``` + +Once defined, these variables can be set during SDK initialization: + +```python +# Python example +client = Client(project_id="proj_123") +``` + +```typescript +// TypeScript example +const client = new Client({ + projectId: "proj_123" +}); +``` + +The SDK will automatically inject the variable value into the appropriate requests, eliminating the need to pass it repeatedly as a parameter. \ No newline at end of file diff --git a/fern/products/openapi-definition/pages/extensions/others.mdx b/fern/products/openapi-definition/pages/extensions/others.mdx new file mode 100644 index 000000000..2df5d6112 --- /dev/null +++ b/fern/products/openapi-definition/pages/extensions/others.mdx @@ -0,0 +1,59 @@ +# OpenAPI Extensions and Variables + +The Fern OpenAPI parser supports several custom extensions to enhance SDK generation capabilities. These extensions can be specified in your OpenAPI definition using `x-` prefixed fields. + +## Core Extensions + +### SDK Variables +The `x-fern-sdk-variables` extension allows you to define variables that can be passed through the SDK constructor and injected into paths and parameters. + +```yaml +x-fern-sdk-variables: + project_id: + type: string + description: "The project ID" + pattern: "^proj_[a-zA-Z0-9]+$" +``` + +Variables defined here can be referenced in path parameters using `x-fern-sdk-variable`: + +```yaml +paths: + /v1/projects/{project_id}/users: + parameters: + - name: project_id + in: path + required: true + schema: + type: string + x-fern-sdk-variable: project_id +``` + +### SDK Configuration +- `x-fern-sdk-group-name` - Groups related endpoints under a common namespace +- `x-fern-sdk-method-name` - Customizes the generated method name +- `x-fern-ignore` - Excludes an endpoint from SDK generation +- `x-fern-sdk-return-value` - Specifies the response field to return + +### Pagination Support +The `x-fern-pagination` extension configures cursor-based pagination: + +```yaml +x-fern-pagination: + cursor: "$request.after" + next_cursor: "$response.page_info.end_cursor" + results: "$response.data" +``` + +### Response Handling +- `x-fern-error-response` - Defines custom error handling +- `x-fern-sdk-async` - Marks an endpoint as async/non-blocking + +## Usage Notes + +- Extensions must be placed at the appropriate level (operation, parameter, etc.) +- Variable patterns use standard regex syntax +- Path references use dot notation (e.g. `$response.data`) +- Generator support may vary by language + +For language-specific implementation details, refer to the [SDK Generators](../generators/overview) documentation. \ No newline at end of file diff --git a/fern/products/sdks/overview/python/configuration.mdx b/fern/products/sdks/overview/python/configuration.mdx index ec8d1dde9..e85115048 100644 --- a/fern/products/sdks/overview/python/configuration.mdx +++ b/fern/products/sdks/overview/python/configuration.mdx @@ -11,7 +11,7 @@ groups: local: generators: - name: fernapi/fern-python - version: 0.7.1 + version: 4.24.0 config: client: class_name: "YourClient" @@ -19,10 +19,8 @@ groups: ## SDK Configuration Options - - - + Client configuration options including SDK variable support through `x-fern-sdk-variables` in OpenAPI specs. @@ -30,6 +28,7 @@ groups: + Whether to exclude types from __init__ exports @@ -41,13 +40,8 @@ groups: ``` - - - - - - + Whether to use a flat directory layout for generated code @@ -62,9 +56,6 @@ groups: Whether or not to include legacy wire tests in the generated SDK - - - If true, treats path parameters as named parameters in endpoint functions. @@ -74,9 +65,11 @@ groups: + Custom package name for the generated SDK + Configuration options for Pydantic model generation @@ -101,8 +94,6 @@ groups: 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. @@ -124,21 +115,16 @@ groups: This changes your declared python dependency, which is not meant to be done often if at all. This is a last resort if any dependencies force you to change your version requirements. - - - Feature flag that enables generation of Python websocket clients. - - - 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. + Whether to include the API name in the generated package name @@ -149,6 +135,31 @@ groups: Whether or not to generate `TypedDicts` instead of Pydantic Models for request objects. - - 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. + + An extension field in OpenAPI specs that allows you to define variables for your SDK client. These variables will be available in the generated client constructor. Variables must be defined in the components section of your OpenAPI spec: + + ```yaml + components: + x-fern-sdk-variables: + project_id: + type: string + description: "The project ID" + pattern: "^proj_[a-zA-Z0-9]+$" + ``` + + Once defined, you can reference these variables in your path parameters with the `x-fern-sdk-variable` extension: + + ```yaml + /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 + ``` + + The generated SDK will handle injecting these variables into API calls automatically when they are provided to the client constructor. \ No newline at end of file diff --git a/fern/products/sdks/overview/typescript/configuration.mdx b/fern/products/sdks/overview/typescript/configuration.mdx index 6fc216209..651231b6a 100644 --- a/fern/products/sdks/overview/typescript/configuration.mdx +++ b/fern/products/sdks/overview/typescript/configuration.mdx @@ -130,9 +130,11 @@ Specify extra peer dependencies meta fields in the generated `package.json`: ```yaml # generators.yml config: - extraPeerDependencies: - react: ">=16.8.0 <19.0.0" - "react-dom": ">=16.8.0 <19.0.0" + extraPeerDependenciesMeta: + react: + optional: true + "react-dom": + optional: true ``` @@ -411,134 +413,44 @@ generate a `jsr.json` as well as a GitHub workflow to publish to JSR. - - Generate WebSocket clients from your AsyncAPI specs. - - - - By default, the client will throw an error if the response from the server -doesn't match the expected type (based on how the response is modeled in the -Fern Definition). - -If `skipResponseValidation` is set to `true`, the client will never throw if the response is misshapen. Instead, the client will log the issue using `console.warn` and return the data (casted to the expected response type). - -Response validation only occurs when the Serde layer is enabled (`noSerdeLayer: false`). The Serde layer is disabled by default (`noSerdeLayer: true`). - - - - -Change the type of stream that is used in the generated SDK. - -* `wrapper`: The streams use a wrapper with multiple underlying implementations to support versions of Node.js before Node.js 18. -* `web`: The streams use the web standard `ReadableStream`. - -The default is `web`. - - - - When `treatUnknownAsAny` is enabled, [unknown types from Fern are generated into TypeScript using `any` instead of the `unknown` type](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-0.html#new-unknown-top-type). - - - -When `useBigInt` is set to `true`, a customized JSON serializer & deserializer is used that will preserve the precision of `bigint`'s, as opposed to the native `JSON.stringify` and `JSON.parse` function which converts `bigint`'s to number's losing precision. - -When combining `useBigInt` with our serialization layer (`no-serde: false`), both the request and response properties that are marked as `long` and `bigint` in OpenAPI/Fern spec, will consistently be `bigint`'s. -However, when disabling the serialization layer (`no-serde: true`), they will be typed as `number | bigint`. + +Configures SDK variables that can be set at client initialization time and will be injected into endpoints when needed. Each variable name maps to a boolean indicating whether it is required. -Here's an overview of what to expect from the generated types when combining `useBigInt` and `noSerde` with the following Fern definition: +```yaml +# generators.yml +config: + sdkVariables: + project_id: true # Required variable + tenant_id: false # Optional variable +``` -*Fern definition*: +The variables will be injected into endpoints based on their declaration in your OpenAPI or Fern definition (via `x-fern-sdk-variables`). For example: ```yaml -types: - ObjectWithOptionalField: - properties: - longProp: long - bigIntProp: bigint +# OpenAPI +x-fern-sdk-variables: + project_id: + type: string + description: "The project ID to use" + pattern: "^proj_[a-zA-Z0-9]+$" ``` -*TypeScript output*: +Generated client: ```typescript -// useBigInt: true -// noSerde: false -interface ObjectWithLongAndBigInt { - longProp: bigint; - bigIntProp: bigint; -} - -// useBigInt: true -// noSerde: true -interface ObjectWithLongAndBigInt { - longProp: bigint | number; - bigIntProp: bigint | number; -} - -// useBigInt: false -// noSerde: false -interface ObjectWithLongAndBigInt { - longProp: number; - bigIntProp: string; -} - -// useBigInt: false -// noSerde: true -interface ObjectWithLongAndBigInt { - longProp: number; - bigIntProp: string; -} +const client = new Client({ + // Required variable + project_id: "proj_123", + // Optional variable + tenant_id: "tenant_456" +}); ``` - - - When `useBrandedStringAliases` is disabled (the default), string aliases are generated as - normal TypeScript aliases: - - ```typescript - // generated code - - export type MyString = string; - - export type OtherString = string; - ``` - When `useBrandedStringAliases` is enabled, string aliases are generated as branded strings. This makes each alias feel like its own type and improves compile-time safety. - - ```yaml - # fern definition - - types: - MyString: string - OtherString: string - ``` - - ```typescript - // generated code - - export type MyString = string & { __MyString: void }; - export const MyString = (value: string): MyString => value as MyString; - - export type OtherString = string & { __OtherString: void }; - export const OtherString = (value: string): OtherString => value as OtherString; - ``` - - ```typescript - // consuming the generated type - - function printMyString(s: MyString): void { - console.log("MyString: " + s); - } - - // doesn't compile, "foo" is not assignable to MyString - printMyString("foo"); - - const otherString = OtherString("other-string"); - // doesn't compile, otherString is not assignable to MyString - printMyString(otherString); - - // compiles - const myString = MyString("my-string"); - printMyString(myString); - ``` + + Generate WebSocket clients from your AsyncAPI specs. + - \ No newline at end of file + + By default, the client will throw an error if the response from the server +doesn't match the expected type (based on how \ No newline at end of file