Fern Definition

Use Fern Definition to define your API

An overview of how to define your API using the Fern Definition format, then use Fern to generate SDKs and API reference documentation for your API.

A Fern Definition is a set of YAML files that describe your API.

Each Fern Definition file may define:

Custom types. Use custom types to build your data model.
Endpoints. Group related endpoints into services.
Errors. An error represents a failed (non-200) response from an endpoint.

Alternatively, you can use the OpenAPI specification format.

Fern generates SDKs and API reference documentation from your Fern Def. Create a fern/ project through one of our Quickstarts then update the Fern Def files in fern/definitions/ with your own. You can configure API-wide settings with the api.yml file.

Once you’ve defined and configured your API, you can run fern generate to generate SDKs or fern generate —docs to generate docs.

Converting to and from OpenAPI

Already have an OpenAPI spec and want to convert it to Fern Definition? Run fern write-definition.
Need to convert your Fern Definition files to an OpenAPI spec to work with OpenAPI tools? Use our OpenAPI generator from your Fern Def.

An example of a Fern Definition

Shown below is a sample from an API defined using Fern Definition. The endpoints are organized into a group called a service, which share a base-path of /store and a default value for auth. The defined custom types (such as Order) are analogous to schemas in OpenAPI.

store.yml

1 service:
2   base-path: /store
3   auth: false
4 
5   endpoints:
6     placeOrder:
7       display-name: Place order
8       docs: Place a new order in the store for a Pet
9       method: POST
10       path: /order
11       request: OrderRequest
12       response: Order
13       errors:
14         - InvalidOrderInputError
15       examples:
16         - request: $OrderRequest.ExampleOrderRequest
17           response: 
18             body: $Order.ExampleOrderResponse
19 
20 types:
21   OrderStatus:
22     enum:
23       - placed
24       - approved
25       - delivered
26 
27   Order:
28     properties:
29       id: optional<integer>
30       petId: optional<integer>
31       quantity: optional<integer>
32       shipDate: optional<datetime>
33       status: optional<OrderStatus>
34       complete: optional<boolean>
35     examples:
36       - name: ExampleOrderResponse
37         value:
38           id: 100004
39           petId: 44
40           quantity: 1
41           status: placed 
42           complete: true
43 
44   OrderRequest:
45     properties:
46       petId: optional<integer>
47       quantity: optional<integer>
48     examples:
49       - name: ExampleOrderRequest
50         value:
51           petId: 44
52           quantity: 1
53 
54 errors:
55   InvalidOrderIDError:
56     status-code: 400
57   OrderNotFoundError:
58     status-code: 404
59     type: Order
60   InvalidOrderInputError:
61     status-code: 400

1	service:
2	base-path: /store
3	auth: false
4
5	endpoints:
6	placeOrder:
7	display-name: Place order
8	docs: Place a new order in the store for a Pet
9	method: POST
10	path: /order
11	request: OrderRequest
12	response: Order
13	errors:
14	- InvalidOrderInputError
15	examples:
16	- request: $OrderRequest.ExampleOrderRequest
17	response:
18	body: $Order.ExampleOrderResponse
19
20	types:
21	OrderStatus:
22	enum:
23	- placed
24	- approved
25	- delivered
26
27	Order:
28	properties:
29	id: optional<integer>
30	petId: optional<integer>
31	quantity: optional<integer>
32	shipDate: optional<datetime>
33	status: optional<OrderStatus>
34	complete: optional<boolean>
35	examples:
36	- name: ExampleOrderResponse
37	value:
38	id: 100004
39	petId: 44
40	quantity: 1
41	status: placed
42	complete: true
43
44	OrderRequest:
45	properties:
46	petId: optional<integer>
47	quantity: optional<integer>
48	examples:
49	- name: ExampleOrderRequest
50	value:
51	petId: 44
52	quantity: 1
53
54	errors:
55	InvalidOrderIDError:
56	status-code: 400
57	OrderNotFoundError:
58	status-code: 404
59	type: Order
60	InvalidOrderInputError:
61	status-code: 400