OpenAPIExtensions

Request + response examples

While OpenAPI has several fields for examples, there is no easy way to associate a request with a response. This is especially useful when you want to show more than one example in your documentation.

x-fern-examples is an array of examples. Each element of the array can contain path-parameters, query-parameters, request and response examples values that are all associated. Optionally, you can add a name field to provide a descriptive label for each example.

If you defined global headers via the x-fern-global-headers extension, you must include the headers in your examples.

openapi.yml
1paths:
2  /users/{userId}:
3    get:
4      x-fern-examples:
5        - name: Headers example # Optional descriptive label
6          headers:
7            custom_api_key: "capi_12345" # header defined using x-global-header extension
8            userpool_id: "pool_67890"    # header defined using x-global-header extension
9        - name: Get user 1234
10          path-parameters:
11            userId: user-1234
12          response:
13            body:
14              name: Foo
15              ssn: 1234
16        - path-parameters:
17            userId: user-4567
18          response:
19            body:
20              name: Foo
21              ssn: 4567
22components:
23  schemas:
24    User:
25      type: object
26      properties:
27        name:
28          type: string
29        ssn:
30          type: integer

Code samples

Fern generators automatically add SDK code samples. If you’d like to specify custom code samples for your example, use code-samples.

openapi.yml
1paths:
2  /users/{userId}:
3    get:
4      x-fern-examples:
5        - path-parameters:
6            userId: user-1234
7          response:
8            body:
9              name: Foo
10              ssn: 1234
11          code-samples:
12            - sdk: typescript
13              code: |
14                import { UserClient } from "...";
15
16                client.users.get("user-1234")