Fern DefinitionAdvanced

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.
View as Markdown

Fern Definition isn’t recommended for new customers and Fern isn’t accepting feature requests for this format. It remains supported for existing users.

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 with headers

When you have global headers defined in your api.yml, you must include them in your examples:

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        - headers:
16            X-App-Id: "app_12345"
17          request:
18            orderId: "online_789"
19            weightInOunces: 5
20          response:
21            body:
22              orderId: "online_789"
23              weightInOunces: 5
24              trackingNumber: "1Z26W8370303469306"
25              price: 2.50

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"