diff --git a/fern/products/sdks/overview/csharp/configuration.mdx b/fern/products/sdks/overview/csharp/configuration.mdx index 740f3ba67..5db42156b 100644 --- a/fern/products/sdks/overview/csharp/configuration.mdx +++ b/fern/products/sdks/overview/csharp/configuration.mdx @@ -18,7 +18,7 @@ groups: ## SDK configuration options - + @@ -30,47 +30,47 @@ groups: - + - + - + - + - + - + - + - + - + - + - + - + - + - + - - + + \ No newline at end of file diff --git a/fern/products/sdks/overview/go/configuration.mdx b/fern/products/sdks/overview/go/configuration.mdx index 348ae0d7a..cf47d81a6 100644 --- a/fern/products/sdks/overview/go/configuration.mdx +++ b/fern/products/sdks/overview/go/configuration.mdx @@ -21,6 +21,53 @@ groups: ## SDK Configuration Options + + + + + + + + + + + + + +Use this option if you plan to depend on the generated Go SDK from within your project, and **not** depend on it as a separate, published Go module. + +If you plan to to distribute the generated Go SDK as a separate, published Go module, use the `module` configuration option instead. + +You can generate the Go SDK code into a `gen/go/api` package with the following `generators.yml` +configuration: + +```yaml {7-8} +default-group: local +groups: + local: + generators: + - name: fernapi/fern-go-sdk + version: 0.13.0 + config: + importPath: github.com///generated/go + output: + location: local-file-system + path: ../generated/go +``` +You must update the `` and `` placeholders +with the relevant elements in your `go.mod` path. In this case, the generated Go SDK uses the same `go.mod` path used by the rest of your Go module. + + + + + + + + + + + + Use this option if you plan to distribute the generated Go SDK as a separate, published Go module. @@ -79,61 +126,14 @@ replace "github.com/your/sdk" v0.0.0 => "path/to/generated/sdk" - - - - -Use this option if you plan to depend on the generated Go SDK from within your project, and **not** depend on it as a separate, published Go module. - -If you plan to to distribute the generated Go SDK as a separate, published Go module, use the `module` configuration option instead. - -You can generate the Go SDK code into a `gen/go/api` package with the following `generators.yml` -configuration: - -```yaml {7-8} -default-group: local -groups: - local: - generators: - - name: fernapi/fern-go-sdk - version: 0.13.0 - config: - importPath: github.com///generated/go - output: - location: local-file-system - path: ../generated/go -``` -You must update the `` and `` placeholders -with the relevant elements in your `go.mod` path. In this case, the generated Go SDK uses the same `go.mod` path used by the rest of your Go module. - - - - - - - - - - - - - - - - - - - - - - + - + - + \ No newline at end of file diff --git a/fern/products/sdks/overview/java/configuration.mdx b/fern/products/sdks/overview/java/configuration.mdx index 52176a2ca..ab376e3cd 100644 --- a/fern/products/sdks/overview/java/configuration.mdx +++ b/fern/products/sdks/overview/java/configuration.mdx @@ -17,17 +17,17 @@ groups: ## SDK Configuration Options - - -The provided string will be used as the client class name. - - + + +The provided string will be used as the client class name. + + Example: @@ -41,26 +41,13 @@ Example: - - - - - - - - When enabled, generates wrapper types for each alias to increase type-safety. -For example, if you have an alias `ResourceId: string` then if this is true, the -generator will generate a `ResourceId.java` file. If false, it will just treat it -as `java.util.String`. + - - - - + @@ -68,13 +55,19 @@ as `java.util.String`. When enabled, generates public constructors for model types. - + + + + - + + + + @@ -86,5 +79,12 @@ config: ``` - + + + + When enabled, generates wrapper types for each alias to increase type-safety. +For example, if you have an alias `ResourceId: string` then if this is true, the +generator will generate a `ResourceId.java` file. If false, it will just treat it +as `java.util.String`. + \ No newline at end of file diff --git a/fern/products/sdks/overview/php/configuration.mdx b/fern/products/sdks/overview/php/configuration.mdx index 44a9cafcc..67e649498 100644 --- a/fern/products/sdks/overview/php/configuration.mdx +++ b/fern/products/sdks/overview/php/configuration.mdx @@ -21,21 +21,20 @@ groups: - - - - + - + - + - + - + + + \ 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 f46107787..ec8d1dde9 100644 --- a/fern/products/sdks/overview/python/configuration.mdx +++ b/fern/products/sdks/overview/python/configuration.mdx @@ -19,6 +19,19 @@ groups: ## SDK Configuration Options + + + + + + + + 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=):` + + + + + If you want to add custom dependencies to your generated SDK, you can specify them using this configuration. For example, to add a dependency on boto3, your config would look like: ``` @@ -34,26 +47,33 @@ groups: - + - + + Whether to follow redirects by default in HTTP requests. - + + 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 - + - - 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. + + If true, treats path parameters as named parameters in endpoint functions. - + + Feature flag that removes the usage of request objects, and instead uses parameters in function signatures where possible. + + + @@ -100,55 +120,35 @@ groups: ``` - - - - - - - - Feature flag that improves imports in the Python SDK by removing nested `resources` directory - - - - Whether to follow redirects by default in HTTP requests. - - - - Feature flag that removes the usage of request objects, and instead uses parameters in function signatures where possible. + + 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. - - If true, treats path parameters as named parameters in endpoint functions. + Feature flag that enables generation of Python websocket clients. - - 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. + - - Whether or not to generate `TypedDicts` instead of Pydantic Models for request objects. + + 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 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. + Whether to generate Pydantic models that implement inheritance when a model utilizes the Fern `extends` keyword. - - - - - 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=):` + + Whether or not to generate `TypedDicts` instead of Pydantic Models for request objects. - - Whether or not to include legacy wire tests in the generated SDK + + 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. \ No newline at end of file diff --git a/fern/products/sdks/overview/ruby/configuration.mdx b/fern/products/sdks/overview/ruby/configuration.mdx index 974a6ab05..0d57997a9 100644 --- a/fern/products/sdks/overview/ruby/configuration.mdx +++ b/fern/products/sdks/overview/ruby/configuration.mdx @@ -18,20 +18,20 @@ groups: ## SDK Configuration Options - + - + - + - + - + - + \ 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 8cc4adf68..9757803be 100644 --- a/fern/products/sdks/overview/typescript/configuration.mdx +++ b/fern/products/sdks/overview/typescript/configuration.mdx @@ -18,36 +18,71 @@ groups: ## SDK configuration options - - When enabled, the generator outputs raw TypeScript files. When disabled (the default), outputs `.js` and `d.ts` files. - - This only applies when dumping code locally. This configuration is ignored when publishing to Github or npm. - - - - When enabled, [`withCredentials`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials) is set to `true` when making network requests. + +Allow fields that are not defined in object schemas. This only applies to serde. - - Generate WebSocket clients from your AsyncAPI specs. - - The default timeout for network requests. In the generated client, this can be overridden at the request level. - - 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). + +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. -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). +`enableInlineTypes: false`: -Response validation only occurs when the Serde layer is enabled (`noSerdeLayer: false`). The Serde layer is disabled by default (`noSerdeLayer: true`). +```typescript +// MyRootType.ts +import * as MySdk from "..."; + +export interface MyRootType { + foo: MySdk.MyRootTypeFoo; +} + +// MyRootTypeFoo.ts +import * as MySdk from "..."; + +export interface MyRootTypeFoo { + bar: MySdk.MyRootTypeFooBar; +} + +// MyRootTypeFooBar.ts +import * as MySdk from "..."; + +export interface MyRootTypeFooBar {} +``` +`enableInlineTypes: true`: + +```typescript +// MyRootType.ts +import * as MySdk from "..."; + +export interface MyRootType { + foo: MyRootType.Foo; +} + +export namespace MyRootType { + export interface Foo { + bar: Foo.Bar; + } + + export namespace Foo { + export interface Bar {} + } +} +``` + +Now users can get the deep nested `Bar` type as follows: +```typescript +import { MyRootType } from MySdk; + +const bar: MyRootType.Foo.Bar = {}; +``` @@ -101,67 +136,8 @@ config: ``` - - 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). - - - - By default, Fern's `optional<>` properties will translate to optional TypeScript properties: - - ```yaml {4} - Person: - properties: - name: string - age: optional - ``` - - ```typescript {3} - interface Person { - name: string; - age?: number; - } - ``` - - When `noOptionalProperties` is enabled, the generated properties are never optional. Instead, the type is generated with `| undefined`. As a result, users must explicitly set the property to a value or `undefined`. - - ```typescript {3} - interface Person { - name: string; - age: number | undefined; - } - ``` - - - -When you specify an object in `packageJson`, it will be merged into the `package.json` file. - -```yaml -# generators.yml -config: - packageJson: - description: The SDK for Acme Corp's API. - author: - name: Acme Corp - url: https://developer.acmecorp.com - email: developers@acmecorp.com - bugs: - url: https://developer.acmecorp.com - email: developers@acmecorp.com -``` - - - -Publish your SDK to [JSR](https://jsr.io/). When enabled, the generator will -generate a `jsr.json` as well as a GitHub workflow to publish to JSR. - - - -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`. + +Choose whether you want to include `node-fetch` to support Node.js versions before Node.js 18, or choose `native` to use the native `fetch` API available in Node.js 18 and later. @@ -187,72 +163,30 @@ Choose whether you want to support Node.js 16 and above (`Node16`), or Node.js 1 * `Node16` uses multiple dependencies to support multipart forms, including `form-data`, `formdata-node`, and `form-data-encoder`. * `Node18` uses the native FormData API, and accepts a wider range of types for file uploads, such as `Buffer`, `File`, `Blob`, `Readable`, `ReadableStream`, `ArrayBuffer`, and `Uint8Array` - -Choose whether you want to include `node-fetch` to support Node.js versions before Node.js 18, or choose `native` to use the native `fetch` API available in Node.js 18 and later. - - - -Specify the path where the source files for the generated SDK should be placed. - - - -Allow fields that are not defined in object schemas. This only applies to serde. - - -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. + -`enableInlineTypes: false`: +Includes the content type and content length from binary responses. The user will receive an object of the following type: ```typescript -// MyRootType.ts -import * as MySdk from "..."; - -export interface MyRootType { - foo: MySdk.MyRootTypeFoo; -} - -// MyRootTypeFoo.ts -import * as MySdk from "..."; - -export interface MyRootTypeFoo { - bar: MySdk.MyRootTypeFooBar; +{ + data: ; + contentLengthInBytes?: number; + contentType?: string; } - -// MyRootTypeFooBar.ts -import * as MySdk from "..."; - -export interface MyRootTypeFooBar {} ``` -`enableInlineTypes: true`: - -```typescript -// MyRootType.ts -import * as MySdk from "..."; - -export interface MyRootType { - foo: MyRootType.Foo; -} - -export namespace MyRootType { - export interface Foo { - bar: Foo.Bar; - } - export namespace Foo { - export interface Bar {} - } -} -``` +`` is `core.BinaryResponse` or a stream, depending on `fileResponseType` setting. + -Now users can get the deep nested `Bar` type as follows: + + When enabled, [`withCredentials`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials) is set to `true` when making network requests. + -```typescript -import { MyRootType } from MySdk; + + -const bar: MyRootType.Foo.Bar = {}; -``` + @@ -344,6 +278,50 @@ By default, names are based on the organization and API names in the Fern Defini + + When enabled, the client doesn't throw errors when a non-200 response is received from the server. Instead, the response is wrapped in an [`ApiResponse`](packages/core-utilities/fetcher/src/APIResponse.ts). + + ```typescript + const response = await client.callEndpoint(...); + if (response.ok) { + console.log(response.body) + } else { + console.error(respons.error) + } + ``` + + + + By default, Fern's `optional<>` properties will translate to optional TypeScript properties: + + ```yaml {4} + Person: + properties: + name: string + age: optional + ``` + + ```typescript {3} + interface Person { + name: string; + age?: number; + } + ``` + + When `noOptionalProperties` is enabled, the generated properties are never optional. Instead, the type is generated with `| undefined`. As a result, users must explicitly set the property to a value or `undefined`. + + ```typescript {3} + interface Person { + name: string; + age: number | undefined; + } + ``` + + + +Prevent the generator from running any scripts such as `yarn format` or `yarn install`. If any of the scripts cause errors, toggling this option will allow you to receive the generated code. + + No serialization/deserialization code is generated by default. The client uses `JSON.parse()` and `JSON.stringify()` instead of the default Serde layer. @@ -359,6 +337,39 @@ No serialization/deserialization code is generated by default. The client uses ` + + When enabled, the generator outputs raw TypeScript files. When disabled (the default), outputs `.js` and `d.ts` files. + + This only applies when dumping code locally. This configuration is ignored when publishing to Github or npm. + + + +When you specify an object in `packageJson`, it will be merged into the `package.json` file. + +```yaml +# generators.yml +config: + packageJson: + description: The SDK for Acme Corp's API. + author: + name: Acme Corp + url: https://developer.acmecorp.com + email: developers@acmecorp.com + bugs: + url: https://developer.acmecorp.com + email: developers@acmecorp.com +``` + + + +Specify the path where the source files for the generated SDK should be placed. + + + +Publish your SDK to [JSR](https://jsr.io/). When enabled, the generator will +generate a `jsr.json` as well as a GitHub workflow to publish to JSR. + + When enabled, property names in the generated code retain their original casing from the API definition instead of being converted to camelCase. @@ -400,6 +411,34 @@ No serialization/deserialization code is generated by default. The client uses ` + + 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. @@ -502,45 +541,4 @@ interface ObjectWithLongAndBigInt { printMyString(myString); ``` - - - - When enabled, the client doesn't throw errors when a non-200 response is received from the server. Instead, the response is wrapped in an [`ApiResponse`](packages/core-utilities/fetcher/src/APIResponse.ts). - - ```typescript - const response = await client.callEndpoint(...); - if (response.ok) { - console.log(response.body) - } else { - console.error(respons.error) - } - ``` - - -### Beta options - - - -Includes the content type and content length from binary responses. The user will receive an object of the following type: - -```typescript -{ - data: ; - contentLengthInBytes?: number; - contentType?: string; -} -``` - -`` is `core.BinaryResponse` or a stream, depending on `fileResponseType` setting. - - - - - - - - - -Prevent the generator from running any scripts such as `yarn format` or `yarn install`. If any of the scripts cause errors, toggling this option will allow you to receive the generated code. - - + \ No newline at end of file