diff --git a/fern/products/sdks/guides/configure-auto-pagination.mdx b/fern/products/sdks/guides/configure-auto-pagination.mdx index f3d7bc65b..c42992cbc 100644 --- a/fern/products/sdks/guides/configure-auto-pagination.mdx +++ b/fern/products/sdks/guides/configure-auto-pagination.mdx @@ -11,84 +11,8 @@ managing pagination complexity manually. This page describes how to configure auto pagination for your API endpoints. -## Setting up auto pagination - -To configure auto pagination, specify the dot-access path to the related request -or response property in the `x-fern-pagination extension` (OpenAPI) or `pagination` -field (Fern Definition). - -For example, if results of `my_nested_object` are located in the subfield -`inner_list`, the dot-access path would be `results: -$response.my_nested_object.inner_list`. - -```yaml {7-10} -MyResponseObject: - type: object - properties: - my_nested_object: - type: object - properties: - inner_list: # location of results - type: array - items: - $ref: '#/components/schemas/MyObject' -``` - - - - - -```yaml Offset {6} -... -paths: - /path/to/my/endpoint: - x-fern-pagination: - offset: $request.page_number - results: $response.results -... -``` - -```yaml Cursor {8} -... -paths: - /path/to/my/endpoint: - get: - x-fern-pagination: - cursor: $request.cursor - next_cursor: $response.next - results: $response.results -... -``` - - - - - - -```yaml Offset {6} -service: - endpoints: - listWithOffsetPagination: - pagination: - offset: $request.page - results: $response.data -``` - -```yaml Cursor {7} -service: - endpoints: - listWithCursorPagination: - pagination: - cursor: $request.starting_after - next_cursor: $response.page.next.starting_after - results: $response.data -``` +## How it works for SDK users - - - - -## Generated SDK Usage @@ -159,3 +83,96 @@ service: + +## Setting up auto pagination + +Setting up auto pagination involves defining your pagination scheme and where +your results are located. + + + + +To set up auto pagination for OpenAPI: + +1. Annotate the desired paginated endpoint with the `x-fern-pagination` extension. +1. Specify the pagination scheme, `offset` or `cursor` +1. Specify where your `results` are located, using dot-access notation. + + + +```yaml Offset {4-6} +... +paths: + /path/to/my/endpoint: + x-fern-pagination: # Add pagination extension + offset: $request.page_number # Specify offset pagination scheme + results: $response.results # Specify result location +... +``` + +```yaml Cursor {5-8} +... +paths: + /path/to/my/endpoint: + get: + x-fern-pagination: # Add pagination extension + cursor: $request.cursor # Specify cursor pagination scheme + next_cursor: $response.next + results: $response.results # Specify result location +... +``` + + + + + For example, if results of `my_nested_object` are located in the subfield + `inner_list`, the dot-access path would be `results: + $response.my_nested_object.inner_list`. + + ```yaml {4, 7} + MyResponseObject: + type: object + properties: + my_nested_object: + type: object + properties: + inner_list: # location of results + type: array + items: + $ref: '#/components/schemas/MyObject' + ``` + + + + + +To set up auto pagination for the Fern Definition: + +1. Annotate the desired paginated endpoint with the `pagination` field. +1. Specify the pagination scheme, `offset` or `cursor` +1. Specify where your `results` are located, using dot-access notation. + + + +```yaml Offset {6} +service: + endpoints: + listWithOffsetPagination: + pagination: # Add pagination field + offset: $request.page # Specify offset pagination scheme + results: $response.data # Specify result location +``` + +```yaml Cursor {7} +service: + endpoints: + listWithCursorPagination: + pagination: # Add pagination field + cursor: $request.starting_after # Specify cursor pagination scheme + next_cursor: $response.page.next.starting_after + results: $response.data # Specify result location +``` + + + + diff --git a/fern/products/sdks/guides/configure-idempotency.mdx b/fern/products/sdks/guides/configure-idempotency.mdx index 3672aff75..d7be1d49e 100644 --- a/fern/products/sdks/guides/configure-idempotency.mdx +++ b/fern/products/sdks/guides/configure-idempotency.mdx @@ -66,7 +66,7 @@ for non-idempotent endpoints. This is to ensure that the user knows exactly which invocations are idempotent and which are not. -## Configuring idempotency headers +### Setting up idempotency headers To set up idempotency headers in your API, you need to do the following in your `overrides` file: 1. Configure the idempotency headers diff --git a/fern/products/sdks/guides/customize-method-names.mdx b/fern/products/sdks/guides/customize-method-names.mdx index 45aa1a7f3..ea7c8a85a 100644 --- a/fern/products/sdks/guides/customize-method-names.mdx +++ b/fern/products/sdks/guides/customize-method-names.mdx @@ -9,58 +9,115 @@ code that matches your API's purpose. For example, instead of `client.postUsers` you can configure your SDK to read `client.users.create()`. -This page covers how to customize method and group names using Fern Definition and OpenAPI specs. - - +## How it works for SDK users -## Configure custom method names in `api.yml` +Here's how developers using your generated SDK would call the customized method +name `client.users.create()` in their applications: - For a Fern Definition, the method name comes from the endpoint directly. - You can specify group and method names directly within your service structure. + + + ```ts + const response = await client.users.create(); + ``` + + + ```python + response = client.users.create() + # or async + response = await async_client.users.create() + ``` + + + ```java + const response = client.users().create(); + ``` + + + ```go + const response = client.Users.Create(); + ``` + + + +Here's how users would call nested groups: + + + + ```ts + const response = await client.admin.users.create(); + ``` + + + ```python + response = client.admin.users.create() + # or async + response = await async_client.admin.users.create() + ``` + + + ```java + const response = client.admin().users().create(); + ``` + + + ```go + const response = client.Admin.Users.Create(); + ``` + + + + + Fern automatically handles choosing the appropriate casing for each SDK + language: `snake_case` in python, `camelCase` in TypeScript and `PascalCase` in + Go, etc. Because of this, you define the endpoint structure once and get + properly formatted methods across all generated SDKs. + + +## Configure method names + +For the Fern Definition, method names are directly mapped from your endpoint and service `base-path`. + +For OpenAPI, use the `x-fern-sdk-group-name` and `x-fern-sdk-method-name` extensions to +explicitly define your method name and grouping. + + + In the example below, Fern will generate a method called `client.users.create()`: -```yaml title="api.yaml" {4, 6} +```yaml title="users.yml" {4, 6} services: http: - UsersService: # specify the group - base-path: /users # HTTP path + UsersService: + base-path: /users # This defines the group/namespace for the methods endpoints: - create: # configure SDK method name + create: # This defines the specific method name within the group method: POST path: "" ``` - - - -## Configure custom method names in `openapi.yaml` + + -You can customize your SDK method names in two ways: - -* **Let Fern parse `operationId` (automatic):** By default, Fern uses your - operation ID to generate method names. Format your operation IDs like - `{tag_name}_{operation_name}` (e.g., `users_get`) and Fern will automatically - generate `users.get()`. If your operation ID doesn't start with a tag, Fern - uses it directly as the method name. - -* **Use the `x-fern-sdk-group-name` and `x-fern-sdk-method-name` extensions - (manual)** to explicitly define your method name and grouping. - -To manually configure your method name, use the `x-fern-sdk-group-name` and -`x-fern-sdk-method-name` extensions. In the example below, Fern will generate a +In the example below, Fern will generate a method called `client.users.create()` for the `POST /users` endpoint. -```yaml title="openapi.yml" {4-5} +```yaml title="openapi.yaml" {4-5} paths: /users: post: x-fern-sdk-group-name: users x-fern-sdk-method-name: create ``` + + By default, Fern uses your operation ID to generate method names. Format your + operation IDs like `{tag_name}_{operation_name}` (e.g., `users_get`) and Fern + will automatically generate `users.get()`. If your operation ID doesn't start + with a tag, Fern uses it directly as the method name. + -## Top level methods +### Top level methods If you omit the `x-fern-sdk-group-name` extension, then the generated SDK method will live at the root of the client rather than nested under a resource group. @@ -73,7 +130,7 @@ paths: x-fern-sdk-method-name: send ``` -## Multiple levels of nesting +### Multiple levels of nesting See how merge.dev uses nested groups [here](https://github.com/merge-api/merge-node-client?tab=readme-ov-file#create-link-token). @@ -93,68 +150,8 @@ paths: - notifications x-fern-sdk-method-name: send ``` - - - -## Casing is automatically configured - -Fern automatically handles choosing the appropriate casing for each SDK -language: `snake_case` in python, `camelCase` in TypeScript and `PascalCase` in - Go, etc. Because of this, you define the endpoint structure once and get - properly formatted methods across all generated SDKs. + + -## Generated SDK examples -Here's how developers using your generated SDK would call the customized method names in their applications: - - - ```ts - const response = await client.users.create(); - ``` - - - ```python - response = client.users.create() - # or async - response = await async_client.users.create() - ``` - - - ```java - const response = client.users().create(); - ``` - - - ```go - const response = client.Users.Create(); - ``` - - - -Here's how users would call nested groups: - - - - ```ts - const response = await client.admin.users.create(); - ``` - - - ```python - response = client.admin.users.create() - # or async - response = await async_client.admin.users.create() - ``` - - - ```java - const response = client.admin().users().create(); - ``` - - - ```go - const response = client.Admin.Users.Create(); - ``` - - diff --git a/fern/products/sdks/guides/setup-local-sdk-previews.mdx b/fern/products/sdks/guides/setup-local-sdk-previews.mdx index cd6e8261e..fe88b0e4a 100644 --- a/fern/products/sdks/guides/setup-local-sdk-previews.mdx +++ b/fern/products/sdks/guides/setup-local-sdk-previews.mdx @@ -4,7 +4,7 @@ description: Use Fern's CLI tool to preview your SDK locally. --- Once you configure your SDK, you can use the `--preview` flag to test generated -SDK code locally before publishing. This allows quick iteration on your Fern definition +SDK code locally before publishing. This allows quick iteration on your SDK as you develop: ```bash