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.

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.

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:

1 types:
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 $.

1 types:
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

1 types:
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  */
25 type 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

1 types:
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  */
10 type Animal = Dog | Cat;

Undiscriminated union

1 types:
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  */
9 type Animal = Dog | Cat;

Aliases

1 types:
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 */ 
5 type 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.

1 service:
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 
37 types:
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 
74 errors:
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:

1 service:
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

1 service:
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"

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:

1 types:
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 $.

1 types:
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

1 types:
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  */
25 type 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

1 types:
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  */
10 type Animal = Dog | Cat;

Undiscriminated union

1 types:
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  */
9 type Animal = Dog | Cat;

Aliases

1 types:
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 */ 
5 type 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.

1 service:
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 
37 types:
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 
74 errors:
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:

1 service:
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

1 service:
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"

1	types:
2	UserId:
3	type: integer
4	examples:
5	- value: hello # not an integer

$	[api]: example.yml -> types -> UserId -> examples[0]
$	Expected example to be an integer. Example is: "hello"

1	types:
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

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	*/
25	type ShipTo = {
26	street1: string;
27	street2?: string;
28	city: string;
29	state: string;
30	postalCode: string;
31	country: Country;
32	isResidential: boolean;
33	};

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"

1	types:
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

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	*/
10	type Animal = Dog \| Cat;

1	types:
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

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	*/
9	type Animal = Dog \| Cat;

1	types:
2	UserId:
3	docs: A unique identifier for a user
4	type: string
5	examples:
6	- value: user-id-123

1	/**
2	* A unique identifier for a user *
3	* @example "user-id-123"
4	*/
5	type UserId = string;

1	service:
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
37	types:
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
74	errors:
75	NotAuthorized:
76	status-code: 401
77	InsufficientFunds:
78	status-code: 422
79	type: InsufficientFundsBody