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: 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 * city: "New York", 18 * state: "NY", 19 * postalCode: "10118", 20 * country: "US", 21 * isResidential: false 22 * } 23 */ 24 type ShipTo = { 25 street1: string; 26 street2?: string; 27 city: string; 28 state: string; 29 postalCode: string; 30 country: Country; 31 isResidential: boolean; 32 };
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 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"