AsyncAPI 转换器
转换 AsyncAPI 软件 文档中,您也可以将 OpenAPI 文档转换为 AsyncAPI 文档.
安装
npm i @asyncapi/converter
使用量
从CLI
要转换控制台中的 AsyncAPI 文档, 需要官方 AsyncAPI 缩写。 。 。 .
如果您没有安装 CLI, 请运行此命令, 以便在您的系统上在全球安装 CLI :
npm install -g @asyncapi/cli
输出的最小使用示例 :
asyncapi convert streetlights.yml -o streetlights2.yml
# Result:
asyncapi: '2.0.0'
channels:
...
转换为特定版本 :
asyncapi convert streetlights.yml -o streetlights2.yml -t 2.3.0
# Result:
asyncapi: '2.3.0'
channels:
...
在联署材料中
const fs = require('fs');
const { convert } = require('@asyncapi/converter')
try {
const asyncapi = fs.readFileSync('streetlights.yml', 'utf-8')
console.log(convert(asyncapi, '2.6.0'));
} catch (e) {
console.error(e);
}
在TS时
import { convert } from '@asyncapi/converter';
import type { ConvertVersion, ConvertOptions } from '@asyncapi/converter';
try {
const toVersion: ConvertVersion = '2.6.0';
const asyncapi = fs.readFileSync('streetlights.yml', 'utf-8')
console.log(convert(asyncapi, toVersion));
} catch (e) {
console.error(e)
}
2.x.x转换为3.x.x
页:1:这个功能仍然是WIP,直到最后发布
3.0.0。 。 。 .
转换为版本 3.x.x 从 2.x.x 有若干假设,在转换前应当知道:
-
输入必须是有效的 AsyncAPI 文档 .
-
外部的参考文献没有解决和转换,即使不正确,它们也没有受到影响.
-
版本
3.0.0,频道标识符不再是它的地址,但由于难以定义一个独特的标识符,我们仍然将地址视为标识符. 如果需要指定地址以外的标识符x-channelId扩展应在给定信道的级别上定义.# 2.x.x channels: users/signup: x-channelId: 'userSignUp' ... users/logout: ... # 3.0.0 channels: userSignUp: ... users/logout: ... -
这个
publish操作被视为receive行动,以及subscribe被视为send行动。 从应用的角度接受默认转换。 如果您想要改变此逻辑, 您需要指定v2tov3.pointOfView配置为client。 。 。 . -
如果操作没有
operationId字段定义,操作的独特标识符将被定义为对操作进行定义的信道的标识符+操作类型,publish或者说subscribe. 同样的情况与信息相同。 然而,这里的优先事项是messageId字段然后接合{publish|subscribe}.messages.{optional index of oneOf messages}。 。 。 .# 2.x.x channels: users/signup: publish: message: ... subscribe: operationId: 'userSignUpEvent' message: oneOf: - messageId: 'userSignUpEventMessage' ... - ... # 3.0.0 channels: users/signup: messages: publish.message: ... userSignUpEventMessage: ... userSignUpEvent.message.1: ... operations: users/signup.publish: action: receive ... userSignUpEvent: action: send ... -
使用范围的安全要求在适当的内在地点界定,其余则作为参照
components.securitySchemes对象. -
如果服务器在频道级别上被定义,它们会被转换为引用在
servers字段. -
在组件中定义的通道和服务器也被转换(除非另作配置).
已知缺失的特性
- 在从 1. x 转换为 2. x 时, 流出 API (使用
stream改为topics或者说events)被正确转换,但有关框架类型和划界符的信息将丢失,直到 协议信息 将为此设立. - 从 2. x 转换为 3. x 时,和
parameter.schema以引用方式定义,它不会研究计划参考,并包括v3参数的任何相关关键词。 它只会创建一个空参数, 但将计划留在组件部分不变 .# 2.x.x channels: "{myParameter}": parameters: myParameter: schema: $ref: "#/components/schemas/mySchema" components: schemas: mySchema: enum: ["test"] default: "test" examples: ["test"] # 3.0.0 channels: "{myParameter}": parameters: myParameter: {} components: schemas: mySchema: enum: ["test"] default: "test" examples: ["test"]
OpenAPI 3.0 到 AsyncAPI 3.0 转换
现在的转换器支持从OpenAPI 3.0到AsyncAPI 3.0的转换. 这个功能可以方便地将现有的OpenAPI 3.0文档转换为AsyncAPI 3.0.
要使用此新转换特性 :
const fs = require('fs');
const { convertOpenAPI } = require('@asyncapi/converter')
try {
const openapi = fs.readFileSync('openapi.yml', 'utf-8')
const asyncapi = convertOpenAPI(openapi, '3.0.0', { from: 'openapi' });
console.log(asyncapi);
} catch (e) {
console.error(e);
}
当从 OpenAPI 转换到 AsyncAPI 时, 您可以使用 perspective 选项。 这使得您可以选择转换是否应该从应用程序或客户端的角度进行
const { convertOpenAPI } = require('@asyncapi/converter')
try {
const asyncapi2 = fs.readFileSync('asyncapi2.yml', 'utf-8')
const asyncapi3 = convertOpenAPI(asyncapi2, '3.0.0', { openAPIToAsyncAPI: { perspective: 'client' } });
console.log(asyncapi3);
} catch (e) {
console.error(e);
}
视角选项可以设置为“ 服务器”( 默认) 或“ 客户端 ” .
-
与
server视角 :action变成receive -
与
client视角 :action变成send
限制
- 内部参考之外: 转换器不支持外部schema文件引用OpenAPI文档内部组件的假想. 在这种情况下,可能需要人工调整转换后的文件.
发展
- 通过安装依赖来设置项目
npm install - 写出密码和测试.
- 确保所有测试通过
npm test
捐款
读取 捐款 向导.
贡献者
感谢这些伟大的人emoji 密钥:
 马西杰·乌尔班奇克 🚧 💻 🐛 👀 ⚠️ 📖 |
 弗朗·门德斯 🚧 💻 🐛 👀 ⚠️ 📖 |
 卢卡斯·戈尔尼茨基 🚧 💻 🐛 👀 ⚠️ 📖 🚇 |
 赫尔曼·施奈德 💻 ⚠️ |
 芭芭拉・克西 🚇 |
 depimomo 语录 💻 |
 奥维尔·戴利 💻 |
 瑞安·R·桑德贝格 💻 |
 莫汉·库马尔 💻 ⚠️ 📖 💡 |
 明图高伊 💻 📖 💡 ⚠️ |
本项目遵循 全部贡献者 规格。 任何捐款都欢迎!