What is an OpenAPI Specification?

The OpenAPI Specification (OAS) is a framework used by developers to document REST APIs. The specification is written in JSON or YAML and contains all of your endpoints, parameters, schemas, and authentication schemes. Fern is compatible with the latest OAS release, which is currently v3.1.1.

Below is an example of an OpenAPI file:

openapi.yml

1 openapi: 3.0.2
2 info:
3   title: Petstore - OpenAPI 3.0
4   description: |-
5     This is a sample Pet Store Server based on the OpenAPI 3.0 specification.
6 paths:
7   "/pet":
8     put:
9       tags:
10       - pet
11       summary: Update an existing pet
12       description: Update an existing pet by Id
13       operationId: updatePet
14       requestBody:
15         description: Update an existent pet in the store
16         content:
17           application/json:
18             schema:
19               "$ref": "#/components/schemas/Pet"
20         required: true
21       responses:
22         '200':
23           description: Successful operation
24           content:
25             application/json:
26               schema:
27                 "$ref": "#/components/schemas/Pet"
28         '400':
29           description: Invalid ID supplied
30         '404':
31           description: Pet not found
32         '405':
33           description: Validation exception
34       security:
35       - api_key
36 components:
37   schemas:
38     Category:
39       type: object
40       properties:
41         id:
42           type: integer
43           format: int64
44           example: 1
45         name:
46           type: string
47           example: Dogs
48     Tag:
49       type: object
50       properties:
51         id:
52           type: integer
53           format: int64
54         name:
55           type: string
56     Pet:
57       required:
58       - name
59       - photoUrls
60       type: object
61       properties:
62         id:
63           type: integer
64           format: int64
65           example: 10
66         name:
67           type: string
68           example: doggie
69         category:
70           "$ref": "#/components/schemas/Category"
71         photoUrls:
72           type: array
73           items:
74             type: string
75         tags:
76           type: array
77           items:
78             "$ref": "#/components/schemas/Tag"
79         status:
80           type: string
81           description: pet status in the store
82           enum:
83           - available
84           - pending
85           - sold
86   securitySchemes:
87     api_key:
88       type: apiKey
89       name: api_key
90       in: header

Best practices

Follow these best practices to ensure your OpenAPI specification generates high-quality SDKs and documentation:

Organize with proper project structure. Follow the instructions at Project structure to clearly organize the directories that contain your definition and other related files.
Add operationId to endpoints. Include a clear operationId for each endpoint to control the function names generated in your SDKs. (Or use extensions to customize group and method names.)

Reference schemas instead of inlining. Define reusable schemas in the components/schemas section and reference them with $ref. This promotes consistency, reduces duplication, and makes maintenance easier.

Example of referencing schemas

openapi.yml

1 paths:
2   /pets:
3     post:
4       requestBody:
5         content:
6           application/json:
7             schema:
8               $ref: '#/components/schemas/Pet'  # Clean reference
9       responses:
10         '200':
11           content:
12             application/json:
13               schema:
14                 $ref: '#/components/schemas/Pet'  # Reused easily
15 components:
16   schemas:
17     Pet:                        # Defined once, used everywhere
18       type: object
19       properties:
20         name:
21           type: string
22         status:
23           type: string
24           enum: [available, pending, sold]

Use overrides and Fern extensions for customization. Customize your specification using Fern extensions housed in an overrides file. This lets you modify generation behavior without changing your core OpenAPI definition.

Once your OpenAPI spec follows these practices, you’re ready to set up your fern folder.

Set up your fern folder

Considering options to generate an OpenAPI spec? Get live support here

Start by initializing your fern folder with an OpenAPI spec

1 fern init --openapi ./path/to/openapi

This will initialize a directory like the following

fern/
  ├─ fern.config.json
  ├─ generators.yml
  └─ openapi/
    ├─ openapi.yml