Skip to content

Commit 117ddfa

Browse files
Document explicit null overrides pattern for deleting parameters
Add comprehensive documentation to parameter-names.mdx explaining how to use explicit null values in overrides files to delete parameters from the base OpenAPI specification. Documentation includes: - Clear explanation of when to use null overrides (duplicate identifiers, deprecated parameters, simplifying SDK interface) - Warning about breaking changes when deleting parameters - Example for deleting a single parameter using 'parameters: [null]' - Example for deleting multiple parameters - Real-world example from Vercel SDK showing how to resolve duplicate identifier errors between query parameters and request body properties This pattern was successfully used to fix TypeScript compilation errors in the Vercel SDK where slug query parameters conflicted with slug request body properties. Related PR: fern-demo/vercel-fern-config#13 Co-Authored-By: [email protected] <[email protected]>
1 parent 5890486 commit 117ddfa

File tree

1 file changed

+83
-0
lines changed

1 file changed

+83
-0
lines changed

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

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,3 +63,86 @@ paths:
6363
type: string
6464
required: false
6565
```
66+
67+
## Delete parameters with null overrides
68+
69+
You can use explicit `null` values in your overrides file to delete parameters from the base specification. This is useful when:
70+
71+
- Resolving duplicate identifier conflicts between query parameters and request body properties
72+
- Removing deprecated or unnecessary parameters from the SDK
73+
- Simplifying the SDK interface by hiding internal parameters
74+
75+
<Warning>
76+
Deleting parameters is a breaking change. Parameters removed via null overrides will not be available in the generated SDK, even though they exist in the base OpenAPI specification.
77+
</Warning>
78+
79+
### Delete a single parameter
80+
81+
To delete the first parameter from an endpoint, use `parameters: [null]` in your overrides file:
82+
83+
```yaml title="overrides.yml" {5-6}
84+
paths:
85+
"/edge-config":
86+
post:
87+
x-fern-sdk-group-name: edgeConfig
88+
x-fern-sdk-method-name: create
89+
parameters:
90+
- null
91+
```
92+
93+
This removes the first parameter defined in the base specification for this endpoint.
94+
95+
### Delete multiple parameters
96+
97+
To delete multiple parameters, add multiple `null` entries:
98+
99+
```yaml title="overrides.yml" {5-8}
100+
paths:
101+
"/users":
102+
get:
103+
x-fern-sdk-group-name: users
104+
x-fern-sdk-method-name: list
105+
parameters:
106+
- null # Deletes first parameter
107+
- null # Deletes second parameter
108+
```
109+
110+
### Real-world example: Resolving duplicate identifiers
111+
112+
A common use case is resolving duplicate identifier errors when a query parameter and request body property have the same name. In this example, both the query parameter `slug` and the request body property `slug` would cause a TypeScript compilation error:
113+
114+
<CodeGroup>
115+
```yaml title="openapi.yml"
116+
paths:
117+
"/edge-config":
118+
post:
119+
operationId: create_edge_config
120+
parameters:
121+
- name: slug
122+
in: query
123+
description: "The Team slug"
124+
schema:
125+
type: string
126+
requestBody:
127+
content:
128+
application/json:
129+
schema:
130+
type: object
131+
properties:
132+
slug:
133+
type: string
134+
description: "The Edge Config slug"
135+
```
136+
137+
```yaml title="overrides.yml"
138+
paths:
139+
"/edge-config":
140+
post:
141+
x-fern-sdk-group-name: edgeConfig
142+
x-fern-sdk-method-name: create
143+
parameters:
144+
- null # Removes the query parameter slug
145+
```
146+
</CodeGroup>
147+
148+
After applying the override, the generated SDK will only include the request body `slug` property, eliminating the duplicate identifier error.

0 commit comments

Comments
 (0)