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.

2 base-path: /store
3 auth: false
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
21 OrderStatus:
22 enum:
23 - placed
24 - approved
25 - delivered
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
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
55 InvalidOrderIDError:
56 status-code: 400
57 OrderNotFoundError:
58 status-code: 404
59 type: Order
60 InvalidOrderInputError:
61 status-code: 400