You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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]>
Copy file name to clipboardExpand all lines: fern/products/api-def/openapi-pages/extensions/parameter-names.mdx
+83Lines changed: 83 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -63,3 +63,86 @@ paths:
63
63
type: string
64
64
required: false
65
65
```
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:
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