diff --git a/fern/products/openapi-def/openapi-def.yml b/fern/products/openapi-def/openapi-def.yml index 419d75e5b..a843620a7 100644 --- a/fern/products/openapi-def/openapi-def.yml +++ b/fern/products/openapi-def/openapi-def.yml @@ -4,7 +4,7 @@ navigation: - page: Authentication path: ./pages/auth.mdx - page: Servers - path: ./pages/servers.mdx + path: ./pages/servers.mdx - section: Endpoints slug: endpoints contents: @@ -17,6 +17,9 @@ navigation: - page: Server-Sent Events path: ./pages/endpoints/sse.mdx slug: sse + - page: others + title: Other + path: ./pages/extensions/others.mdx - section: Extensions slug: extensions contents: @@ -38,7 +41,7 @@ navigation: - page: Overlay Customizations path: ./pages/overrides.mdx - page: Sync your OpenAPI Specification - path: ./pages/automation.mdx + path: ./pages/automation.mdx - section: Integrate your Server Framework slug: frameworks contents: 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..d5f621f1d --- /dev/null +++ b/fern/products/openapi-definition/pages/extensions/others.mdx @@ -0,0 +1,91 @@ +# OpenAPI Extension Headers + +The following extension headers are supported in Fern's OpenAPI implementation: + +## x-fern-sdk-variables + +Allows defining reusable variables that can be referenced across SDK operations. Variables defined here will be available as client constructor parameters. + +```yaml +x-fern-sdk-variables: + project_id: + type: string + description: "The project ID" + pattern: "^proj_[a-zA-Z0-9]+$" +``` + +Variables can then 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 +``` + +This allows SDK users to provide the variable once during client initialization rather than for each API call. + +## x-fern-sdk-group-name + +Groups related operations together in the generated SDK. Operations with the same group name will be organized under a common namespace/class. + +```yaml +paths: + /users: + get: + x-fern-sdk-group-name: users +``` + +## x-fern-sdk-method-name + +Customizes the method name for an operation in the generated SDK. + +```yaml +paths: + /users: + get: + x-fern-sdk-method-name: list +``` + +## x-fern-ignore + +Excludes an operation from the generated SDK when set to `true`. + +```yaml +paths: + /internal/metrics: + get: + x-fern-ignore: true +``` + +## x-fern-pagination + +Configures pagination behavior for list operations. Requires specifying cursor and results fields. + +```yaml +paths: + /users: + get: + x-fern-pagination: + cursor: "$request.after" + next_cursor: "$response.page_info.end_cursor" + results: "$response.data" +``` + +## x-fern-sdk-return-value + +Specifies which part of the response should be returned from SDK methods. + +```yaml +paths: + /users/{id}: + get: + x-fern-sdk-return-value: data +``` + +For complete OpenAPI examples using these extensions, see the [OpenAPI Quick Start guide](/openapi-definition/quickstart). \ 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 1c0eb6af7..a2b193e8b 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: + When enabled, types will not be exported in the package's __init__.py file. @@ -40,12 +42,15 @@ groups: + Additional development dependencies to include in the generated package. + Optional package extras/features to include in setup.py. + When enabled, generates a flatter package 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 enabled, generates additional utilities for union types. @@ -72,12 +78,9 @@ 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 @@ -92,6 +95,7 @@ groups: + Configuration options for Pydantic model generation. @@ -112,12 +116,10 @@ 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. @@ -140,6 +142,23 @@ groups: + Custom pyproject.toml content to include in the generated package. + + + + Variables that can be set once when instantiating the client and used across multiple requests. For OpenAPI specs, these are defined using the `x-fern-sdk-variables` extension. Example: + + ```yaml + x-fern-sdk-variables: + project_id: + type: string + description: The project ID to use for all requests + ``` + + This allows setting the variable once when creating the client: + ```python + client = Client(project_id="proj_123") + ``` @@ -147,6 +166,7 @@ groups: + When true, skips code formatting of the generated SDK. @@ -154,6 +174,7 @@ groups: + When true, includes the API name in the generated package name. diff --git a/fern/products/sdks/overview/typescript/configuration.mdx b/fern/products/sdks/overview/typescript/configuration.mdx index 6fc216209..705e02306 100644 --- a/fern/products/sdks/overview/typescript/configuration.mdx +++ b/fern/products/sdks/overview/typescript/configuration.mdx @@ -11,7 +11,7 @@ groups: local: generators: - name: fernapi/fern-typescript-sdk - version: + version: config: namespaceExport: Acme ``` @@ -23,12 +23,21 @@ Allow fields that are not defined in object schemas. This only applies to serde. +When enabled, bundles the SDK into a single file. The default timeout for network requests. In the generated client, this can be overridden at the request level. + +When enabled, supports the `x-fern-sdk-*` extension properties in your OpenAPI specification. These include: +- `x-fern-sdk-variable`: Path parameters that should be injected by the client constructor +- `x-fern-sdk-group-name`: Custom service group name for endpoints +- `x-fern-sdk-method-name`: Custom method name for endpoints +- `x-fern-ignore`: Skip generating code for this endpoint/component + + When enabled, the inline schemas will be generated as nested types in TypeScript. This results in cleaner type names and a more intuitive developer experience. @@ -130,9 +139,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 ``` @@ -184,9 +195,11 @@ Includes the content type and content length from binary responses. The user wil +When enabled, union types will include an "other" variant for unrecognized values. +When enabled, generates utility functions for union type members. @@ -422,123 +435,4 @@ 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`. - -Here's an overview of what to expect from the generated types when combining `useBigInt` and `noSerde` with the following Fern definition: - -*Fern definition*: - -```yaml -types: - ObjectWithOptionalField: - properties: - longProp: long - bigIntProp: bigint -``` - -*TypeScript output*: - -```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; -} -``` - - - - - 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); - ``` - - \ No newline at end of file +Response validation only occurs when the \ No newline at end of file