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. 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        - headers:
6            custom_api_key: "capi_12345" # header defined using x-global-header extension
7            userpool_id: "pool_67890"    # header defined using x-global-header extension
8        - path-parameters:
9            userId: user-1234
10          response:
11            body:
12              name: Foo
13              ssn: 1234
14        - path-parameters:
15            userId: user-4567
16          response:
17            body:
18              name: Foo
19              ssn: 4567
20components:
21  schemas:
22    User:
23      type: object
24      properties:
25        name:
26          type: string
27        ssn:
28          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")