跳到导航

什么是 AsyncAPI 规范?

以 Markdown 格式查看

Fern 支持为 TypeScript、Python、Java 和 C# 生成 AsyncAPI SDK。提交 issue 来请求支持其他语言。

AsyncAPI 规范是开发人员用来文档化事件驱动 API 的框架。该规范使用 JSON 或 YAML 编写,包含您的所有通道、消息、模式和身份验证方案。Fern 与 AsyncAPI 规范 v2.6.0v3.0.0 兼容。

以下是一个 AsyncAPI 文件的示例:

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

设置您的 fern 文件夹

1

创建您的 fern 目录

在您的项目根目录中创建一个 fern/ 文件夹。

fern
2

添加您的 AsyncAPI 规范

将您的 AsyncAPI 规范添加到 fern 目录中。您可以将其放在名为 asyncapi 的子文件夹中,或直接放在 fern 目录中。

fern
asyncapi
asyncapi.yml
3

创建 fern.config.json 文件

在您的 fern 目录中添加一个 fern.config.json 文件,其中列出您的组织和当前版本的 Fern CLI:

fern.config.json
{
"organization": "your-organization",
"version": "5.23.3"
}
fern
fern.config.json
asyncapi
asyncapi.yml
4

创建 generators.yml 文件

在您的 fern 目录中创建一个 generators.yml 文件,并添加对您的 AsyncAPI 规范的引用:

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

您的最终目录结构:

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