Skip to navigation
AsyncAPI

What is an AsyncAPI specification?

View as Markdown

Fern supports AsyncAPI SDK generation for TypeScript, Python, Java, C#, and Rust. File an issue to request additional languages.

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
asyncapi: 3.0.0
info:
  title: User Notification Service
  version: 1.0.0
  description: |
    Service that handles user notifications through various channels
    including email, SMS, and push notifications.
channels:
  user/signup:
    address: user/signup
    messages:
      UserSignedUp:
        $ref: '#/components/messages/UserSignedUp'
  notification/send:
    address: notification/send
    messages:
      SendNotification:
        $ref: '#/components/messages/SendNotification'
operations:
  onUserSignup:
    action: receive
    channel:
      $ref: '#/channels/user~1signup'
    summary: User signup event
    description: Triggered when a user signs up for the service
  sendNotification:
    action: send
    channel:
      $ref: '#/channels/notification~1send'
    summary: Send notification
    description: Send a notification to a user
components:
  messages:
    UserSignedUp:
      name: UserSignedUp
      title: User Signed Up
      summary: User has signed up for the service
      contentType: application/json
      payload:
        $ref: '#/components/schemas/User'
    SendNotification:
      name: SendNotification
      title: Send Notification
      summary: Send a notification to a user
      contentType: application/json
      payload:
        $ref: '#/components/schemas/Notification'
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the user
        email:
          type: string
          format: email
          description: User's email address
        name:
          type: string
          description: User's full name
        createdAt:
          type: string
          format: date-time
          description: When the user was created
      required:
        - id
        - email
        - name
    Notification:
      type: object
      properties:
        userId:
          type: string
          format: uuid
          description: ID of the user to notify
        type:
          type: string
          enum: [email, sms, push]
          description: Type of notification to send
        message:
          type: string
          description: Message content
        priority:
          type: string
          enum: [low, medium, high, urgent]
          default: medium
          description: Priority level of the notification
      required:
        - userId
        - type
        - message

Set up your fern folder

1

Create your fern directory

Create a fern/ folder in your project root.

fern
2

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
3

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
{
    "organization": "your-organization",
    "version": "5.23.3"
}
fern
fern.config.json
asyncapi
asyncapi.yml
4

Create a generators.yml file

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

generators.yml
# Your API definition
api: 
  specs: 
    - asyncapi: ./asyncapi/asyncapi.yml
groups:
  external:
    generators:
      # Your generator configurations here

Your final directory structure:

fern
fern.config.json
generators.yml
asyncapi
asyncapi.yml