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.

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        - path-parameters:
12            userId: user-4567
13          response:
14            body:
15              name: Foo
16              ssn: 4567
17components:
18  schemas:
19    User:
20      type: object
21      properties:
22        name:
23          type: string
24        ssn:
25          type: integer

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")

If you’re on the Fern Basic plan or higher for SDKs you won’t have to worry about manually adding code samples! Our generators do that for you.