Examples in Fern Definition

Use Fern Definition to add API examples that are shown in comments of SDKs, API Reference documentation, and a Postman collection.

You can add examples for types and endpoints. Examples are shown as comments in your SDKs, in the request & response of your documentation, and in a Postman Collection.

Validation

The Fern CLI validates that your examples match the expected types. The following won’t compile:

1types:
2  UserId:
3    type: integer
4    examples:
5      - value: hello # not an integer
CLI Error Message
$[api]: example.yml -> types -> UserId -> examples[0]
>       Expected example to be an integer. Example is: "hello"

Referencing examples

You can reference an example from another type, endpoint, or error.

Just like types, you can compose examples. To reference an example from another type, use $.

1types:
2  UserId:
3    type: integer
4    examples:
5      - name: Example1
6        value: user-id-123
7
8  User:
9    properties:
10      id: UserId
11      name: string
12    examples:
13      - value:
14          id: $UserId.Example1
15          name: Jane Smith

Examples for types

Objects

1types:
2  ShipTo:
3    properties:
4      street1: string
5      street2: optional<string>
6      city: string
7      state: string
8      postalCode: string
9      country: Country
10      isResidential: boolean
11    examples:
12      - name: WhiteHouse
13        value:
14          street1: 1600 Pennsylvania Avenue NW
15          city: Washington DC
16          state: Washington DC
17          postalCode: "20500"
18          country: US
19          isResidential: true
20      - name: EmpireStateBuilding
21        value:
22          street1: 350 5th Ave
23          street2: Attn: Maintenance Department
24          city: New York
25          state: NY
26          postalCode: "10118"
27          country: US
28          isResidential: false
Generated TypeScript SDK
1/**
2 * Represents a shipping address.
3 * 
4 * The White House address
5 * @example {
6 *  street1: "1600 Pennsylvania Avenue NW",
7 *  city: "Washington DC",
8 *  state: "Washington DC",
9 *  postalCode: "20500",
10 *  country: "US",
11 *  isResidential: true
12 * }
13 * 
14 * * The Empire State Building address
15 * @example {
16 *  street1: "350 5th Ave",
17 *  street2: "Attn: Maintenance Department",
18 *  city: "New York",
19 *  state: "NY",
20 *  postalCode: "10118",
21 *  country: "US",
22 *  isResidential: false
23 * }
24 */
25type ShipTo = {
26  street1: string;
27  street2?: string;
28  city: string;
29  state: string;
30  postalCode: string;
31  country: Country;
32  isResidential: boolean;
33};

Lists

1 Shipments:
2    type: list<ShipmentStatus>
3    examples:
4      - name: Default
5        value:
6          - status: "InTransit"
7            estimatedDeliveryDate: "2024-01-11"
8          - status: "Delivered"
9            estimatedDeliveryDate: "2024-01-13"

Unions

Discriminated union

1types:
2  Animal:
3    union:
4      dog: Dog
5      cat: Cat
6    examples:
7      - value:
8          type: dog
9          likesToWoof: true
10  Dog:
11    properties:
12      likesToWoof: boolean
13  Cat:
14    properties:
15      likesToMeow: boolean
Generated TypeScript SDK
1/**
2 * Represents an animal, which can be either a Dog or a Cat.
3 *
4 * Example of a Dog:
5 * @example {
6 *  type: "dog",
7 *  likesToWoof: true
8 * }
9 */
10type Animal = Dog | Cat;

Undiscriminated union

1types:
2  Animal:
3    discriminated: false
4    union:
5      - Dog
6      - Cat
7    examples:
8      - value:
9          likesToMeow: true
10  Dog:
11    properties:
12      likesToWoof: boolean
13  Cat:
14    properties:
15      likesToMeow: boolean
Generated TypeScript SDK
1/**
2 * Represents an Animal, which can be either a Dog or a Cat.
3 *
4 * Example of an Animal as a Cat:
5 * @example {
6 *  likesToMeow: true
7 * }
8 */
9type Animal = Dog | Cat;

Aliases

1types:
2  UserId:
3    docs: A unique identifier for a user
4    type: string
5    examples:
6      - value: user-id-123
Generated TypeScript SDK
1/** 
2* A unique identifier for a user * 
3* @example "user-id-123" 
4*/ 
5type UserId = string;

Examples for endpoints

You can add examples of successful and error responses for your endpoints. Examples can reference the examples of types to avoid duplication.

1service:
2  auth: true
3  base-path: ""
4  endpoints:
5    CreateShippingLabel:
6      docs: Create a new shipping label.
7      method: POST
8      path: /shipping
9      request: CreateShippingLabelRequest
10      response: ShippingLabel
11      errors:
12        - NotAuthorized
13        - InsufficientFunds
14      examples:
15        # A successful response that doesn't reference other examples.
16        - request:
17            orderId: "online_789"
18            weightInOunces: 5
19          response:
20            body:
21              orderId: "online_789"
22              weightInOunces: 5
23              trackingNumber: "1Z26W8370303469306"
24              price: 2.50
25
26        # A successful response that uses references.
27        - request: $CreateShippingLabelRequest.SuccessfulRequest
28          response:
29            body: $ShippingLabel.Default
30
31        # An error response.
32        - request: $CreateShippingLabelRequest.InsufficientFundsRequest
33          response:
34            error: InsufficientFunds
35            body: $InsufficientFundsBody.Default
36
37types:
38  CreateShippingLabelRequest:
39    properties:
40      orderId: string
41      weightInOunces: integer
42    examples:
43      - name: SuccessfulRequest
44        value:
45          orderId: "online_123"
46          weightInOunces: 13
47      - name: InsufficientFundsRequest
48        value:
49          orderId: "online_456"
50          weightInOunces: 2000
51
52  ShippingLabel:
53    properties:
54      orderId: string
55      weightInOunces: integer
56      trackingNumber: string
57      price: double
58    examples:
59      - name: Default
60        value:
61          orderId: "online_123"
62          weightInOunces: 13
63          trackingNumber: "1Z12345E0205271688"
64          price: 12.35
65
66  InsufficientFundsBody:
67    properties:
68      message: string
69    examples:
70      - name: Default
71        value:
72          message: "Insufficient funds to create shipping label."
73
74errors:
75  NotAuthorized:
76    status-code: 401
77  InsufficientFunds:
78    status-code: 422
79    type: InsufficientFundsBody

Examples for path parameters

1service:
2  auth: true
3  base-path: ""
4  endpoints:
5    TrackShipment:
6      docs: Track the status of a shipment.
7      method: GET
8      path: /shipping/{trackingNumber}
9      path-parameters: 
10        trackingNumber: string
11      response: ShipmentStatus
12      examples:
13        - path-parameters: 
14            trackingNumber: "1Z26W8370303469306"
15          response:
16            body:
17              status: "InTransit"
18              estimatedDeliveryDate: "2024-01-11"