What is an AsyncAPI Specification?

Fern only supports AsyncAPI SDK generation for TypeScript and Python.

The AsyncAPI Specification is a framework used by developers to document event-driven APIs. The specification is written in JSON or YAML and contains all of your channels, messages, schemas, and authentication schemes. Fern is compatible with AsyncAPI specification v2.6.0 and v3.0.0.

Below is an example of an AsyncAPI file:

asyncapi.yml

1 asyncapi: 3.0.0
2 info:
3   title: User Notification Service
4   version: 1.0.0
5   description: |
6     Service that handles user notifications through various channels
7     including email, SMS, and push notifications.
8 channels:
9   user/signup:
10     address: user/signup
11     messages:
12       UserSignedUp:
13         $ref: '#/components/messages/UserSignedUp'
14   notification/send:
15     address: notification/send
16     messages:
17       SendNotification:
18         $ref: '#/components/messages/SendNotification'
19 operations:
20   onUserSignup:
21     action: receive
22     channel:
23       $ref: '#/channels/user~1signup'
24     summary: User signup event
25     description: Triggered when a user signs up for the service
26   sendNotification:
27     action: send
28     channel:
29       $ref: '#/channels/notification~1send'
30     summary: Send notification
31     description: Send a notification to a user
32 components:
33   messages:
34     UserSignedUp:
35       name: UserSignedUp
36       title: User Signed Up
37       summary: User has signed up for the service
38       contentType: application/json
39       payload:
40         $ref: '#/components/schemas/User'
41     SendNotification:
42       name: SendNotification
43       title: Send Notification
44       summary: Send a notification to a user
45       contentType: application/json
46       payload:
47         $ref: '#/components/schemas/Notification'
48   schemas:
49     User:
50       type: object
51       properties:
52         id:
53           type: string
54           format: uuid
55           description: Unique identifier for the user
56         email:
57           type: string
58           format: email
59           description: User's email address
60         name:
61           type: string
62           description: User's full name
63         createdAt:
64           type: string
65           format: date-time
66           description: When the user was created
67       required:
68         - id
69         - email
70         - name
71     Notification:
72       type: object
73       properties:
74         userId:
75           type: string
76           format: uuid
77           description: ID of the user to notify
78         type:
79           type: string
80           enum: [email, sms, push]
81           description: Type of notification to send
82         message:
83           type: string
84           description: Message content
85         priority:
86           type: string
87           enum: [low, medium, high, urgent]
88           default: medium
89           description: Priority level of the notification
90       required:
91         - userId
92         - type
93         - message

Set up your fern folder

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

Create your fern directory

Create a fern/ folder in your project root.

fern/

Add your AsyncAPI specification

Add your AsyncAPI spec to the fern directory. You can place it in a subfolder called asyncapi or directly in the fern directory.

fern/
  └─ asyncapi/
    └─ asyncapi.yml

Create a `fern.config.json` file

Add a fern.config.json file in your fern directory that lists your organization and the current version of the Fern CLI:

fern.config.json

1 {
2     "organization": "your-organization",
3     "version": "0.77.5"
4 }

fern/
  ├─ fern.config.json
  └─ asyncapi/
    └─ asyncapi.yml

Create a `generators.yml` file

Create a generators.yml file in your fern directory and add a reference to your AsyncAPI spec:

generators.yml

1 # Your API definition
2 api: 
3   specs: 
4     - asyncapi: ./asyncapi/asyncapi.yml
5 
6 groups:
7   external:
8     generators:
9       # Your generator configurations here

Your final directory structure:

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