Skip to content

Commit c2218a5

Browse files
devalogdevalog
authored
(sdks/api definitions) Restructure and snippetize repetitive content (#1331)
1 parent 91cf03b commit c2218a5

File tree

3 files changed

+55
-108
lines changed

3 files changed

+55
-108
lines changed

‎fern/products/api-def/openapi-pages/extensions/method-names.mdx‎

Lines changed: 2 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,6 @@
11
---
2-
title: Customize SDK Method Names
2+
title: Customize SDK method names
33
description: Use `x-fern-sdk-method-name` and `x-fern-sdk-group-name` to finetune SDK naming.
44
---
55

6-
## Operation IDs
7-
8-
By default, if you have no extensions present, Fern will try to use your operation ID to generate idiomatic
9-
method names for the SDK. We typically recommend formatting your operation IDs like `{tag_name}_{operation_name}`.
10-
11-
For example, for an endpoint that has the tag `users` and the operation id `users_get`, we will generate an SDK
12-
method that is `users.get()`. If your operation id does not start with a tag, then we will simply use it as the method name.
13-
14-
## Usage
15-
16-
<Note>
17-
The `x-fern-sdk-group-name` and `x-fern-sdk-method-name` extensions allow you to customize the generated SDK method
18-
names.
19-
</Note>
20-
21-
In the example below, Fern will generate a method called `client.users.create()` for the `POST /users` endpoint.
22-
23-
```yaml title="openapi.yaml"
24-
paths:
25-
/users:
26-
post:
27-
x-fern-sdk-group-name: users
28-
x-fern-sdk-method-name: create
29-
```
30-
31-
## Top level methods
32-
33-
If you omit the `x-fern-sdk-group-name` extension, then the generated SDK method will live at the root.
34-
In the example below, Fern will generate a method called `client.send()`:
35-
36-
```yaml title="openapi.yaml"
37-
paths:
38-
/send:
39-
post:
40-
x-fern-sdk-method-name: send
41-
```
42-
43-
## Multiple levels of nesting
44-
45-
If you add more than one `x-fern-sdk-group-name` extension, then the generated SDK will nest group names.
46-
The order of the group names is preserved in the generated SDK method.
47-
48-
In the example below, Fern will generate a method called `client.users.notifications.send()`:
49-
50-
```yaml title="openapi.yaml"
51-
paths:
52-
/users/notifications:
53-
post:
54-
x-fern-sdk-group-name:
55-
- users
56-
- notifications
57-
x-fern-sdk-method-name: send
58-
```
6+
<Markdown src="/snippets/open-api-method-names.mdx" />

‎fern/products/sdks/guides/customize-method-names.mdx‎

Lines changed: 3 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -76,67 +76,16 @@ Here's how users would call nested groups:
7676

7777
## Configure method names
7878

79-
For the Fern Definition, method names are directly mapped from your endpoint and service `base-path`.
80-
81-
For OpenAPI, use the `x-fern-sdk-group-name` and `x-fern-sdk-method-name` extensions to
82-
explicitly define your method name and grouping.
83-
8479
<AccordionGroup>
8580
<Accordion title="OpenAPI">
8681

87-
In the example below, Fern will generate a
88-
method called `client.users.create()` for the `POST /users` endpoint.
89-
90-
```yaml title="openapi.yaml" {4-5}
91-
paths:
92-
/users:
93-
post:
94-
x-fern-sdk-group-name: users
95-
x-fern-sdk-method-name: create
96-
```
97-
<Note title="Fern automatically parses `operationId`">
98-
By default, Fern uses your operation ID to generate method names. Format your
99-
operation IDs like `{tag_name}_{operation_name}` (e.g., `users_get`) and Fern
100-
will automatically generate `users.get()`. If your operation ID doesn't start
101-
with a tag, Fern uses it directly as the method name.
102-
</Note>
103-
104-
### Top level methods
105-
106-
If you omit the `x-fern-sdk-group-name` extension, then the generated SDK method
107-
will live at the root of the client rather than nested under a resource group.
108-
In the example below, Fern will generate a method called `client.send()`:
109-
110-
```yaml title="openapi.yaml" {4}
111-
paths:
112-
/send:
113-
post:
114-
x-fern-sdk-method-name: send
115-
```
116-
117-
### Multiple levels of nesting
118-
119-
<Note>
120-
See how merge.dev uses nested groups [here](https://github.com/merge-api/merge-node-client?tab=readme-ov-file#create-link-token).
121-
</Note>
122-
123-
If you add more than one `x-fern-sdk-group-name` extension, then the generated SDK will nest group names.
124-
The order of the group names is preserved in the generated SDK method.
82+
<Markdown src="/snippets/open-api-method-names.mdx" />
12583

126-
In the example below, Fern will generate a method called `client.users.notifications.send()`:
127-
128-
```yaml title="openapi.yaml"
129-
paths:
130-
/users/notifications:
131-
post:
132-
x-fern-sdk-group-name:
133-
- users
134-
- notifications
135-
x-fern-sdk-method-name: send
136-
```
13784
</Accordion>
13885
<Accordion title="Fern Definition">
13986

87+
For the Fern Definition, method names are directly mapped from your endpoint and service `base-path`.
88+
14089
In the example below, Fern will generate a method called `client.users.create()`:
14190

14291
```yaml title="users.yml" {4, 6}

‎fern/snippets/open-api-method-names.mdx‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
Use the `x-fern-sdk-group-name` and `x-fern-sdk-method-name` extensions to control how endpoints are organized in your SDK.
2+
3+
<Note title="Fern automatically parses `operationId`">
4+
If no extensions are present, Fern uses your operation ID to generate SDK method names. Format operation IDs as `{tag_name}_{operation_name}` (example: `users_get`) to automatically generate methods like `users.get()`. If the operation ID doesn't start with a tag, Fern uses it directly as the method name.
5+
</Note>
6+
7+
In the example below, Fern will generate a
8+
method called `client.users.create()` for the `POST /users` endpoint.
9+
10+
```yaml title="openapi.yaml" {4-5}
11+
paths:
12+
/users:
13+
post:
14+
x-fern-sdk-group-name: users
15+
x-fern-sdk-method-name: create
16+
```
17+
18+
### Top level methods
19+
20+
If you omit the `x-fern-sdk-group-name` extension, the generated SDK method
21+
will live at the root of the client rather than nested under a resource group.
22+
In the example below, Fern will generate a method called `client.send()`:
23+
24+
```yaml title="openapi.yaml" {4}
25+
paths:
26+
/send:
27+
post:
28+
x-fern-sdk-method-name: send
29+
```
30+
31+
### Multiple levels of nesting
32+
33+
<Note>
34+
See how merge.dev uses nested groups [here](https://github.com/merge-api/merge-node-client?tab=readme-ov-file#create-link-token).
35+
</Note>
36+
37+
If you add more than one `x-fern-sdk-group-name` extension, then the generated SDK will nest group names.
38+
The generated SDK method preserves the order of group names.
39+
40+
In the example below, Fern will generate a method called `client.users.notifications.send()`:
41+
42+
```yaml title="openapi.yaml"
43+
paths:
44+
/users/notifications:
45+
post:
46+
x-fern-sdk-group-name:
47+
- users
48+
- notifications
49+
x-fern-sdk-method-name: send
50+
```

0 commit comments

Comments
 (0)