|
| 1 | +# OpenAPI Extensions and Variables |
| 2 | + |
| 3 | +The Fern OpenAPI parser supports several custom extensions to enhance SDK generation capabilities. These extensions can be specified in your OpenAPI definition using `x-` prefixed fields. |
| 4 | + |
| 5 | +## Core Extensions |
| 6 | + |
| 7 | +### SDK Variables |
| 8 | +The `x-fern-sdk-variables` extension allows you to define variables that can be passed through the SDK constructor and injected into paths and parameters. |
| 9 | + |
| 10 | +```yaml |
| 11 | +x-fern-sdk-variables: |
| 12 | + project_id: |
| 13 | + type: string |
| 14 | + description: "The project ID" |
| 15 | + pattern: "^proj_[a-zA-Z0-9]+$" |
| 16 | +``` |
| 17 | +
|
| 18 | +Variables defined here can be referenced in path parameters using `x-fern-sdk-variable`: |
| 19 | + |
| 20 | +```yaml |
| 21 | +paths: |
| 22 | + /v1/projects/{project_id}/users: |
| 23 | + parameters: |
| 24 | + - name: project_id |
| 25 | + in: path |
| 26 | + required: true |
| 27 | + schema: |
| 28 | + type: string |
| 29 | + x-fern-sdk-variable: project_id |
| 30 | +``` |
| 31 | + |
| 32 | +### SDK Configuration |
| 33 | +- `x-fern-sdk-group-name` - Groups related endpoints under a common namespace |
| 34 | +- `x-fern-sdk-method-name` - Customizes the generated method name |
| 35 | +- `x-fern-ignore` - Excludes an endpoint from SDK generation |
| 36 | +- `x-fern-sdk-return-value` - Specifies the response field to return |
| 37 | + |
| 38 | +### Pagination Support |
| 39 | +The `x-fern-pagination` extension configures cursor-based pagination: |
| 40 | + |
| 41 | +```yaml |
| 42 | +x-fern-pagination: |
| 43 | + cursor: "$request.after" |
| 44 | + next_cursor: "$response.page_info.end_cursor" |
| 45 | + results: "$response.data" |
| 46 | +``` |
| 47 | + |
| 48 | +### Response Handling |
| 49 | +- `x-fern-error-response` - Defines custom error handling |
| 50 | +- `x-fern-sdk-async` - Marks an endpoint as async/non-blocking |
| 51 | + |
| 52 | +## Usage Notes |
| 53 | + |
| 54 | +- Extensions must be placed at the appropriate level (operation, parameter, etc.) |
| 55 | +- Variable patterns use standard regex syntax |
| 56 | +- Path references use dot notation (e.g. `$response.data`) |
| 57 | +- Generator support may vary by language |
| 58 | + |
| 59 | +For language-specific implementation details, refer to the [SDK Generators](../generators/overview) documentation. |
0 commit comments