异步API文档101
#node #nestjs #documentation

async API文档用于记录事件驱动系统（例如Kafka事件）中的事件。所有事件DTO都存储在一个地方。它支持YAML和JSON格式。

它包含有关渠道和组件的信息。频道和组件分别通过其消息和DTO模式定义。

{
  "asyncapi": "2.6.0",
  "info": {
    "title": "Events docs",
    "version": "1.0.0"
  },
  "channels": {
    "topic_name": {
      "publish": {
        "message": {
          "schemaFormat": "application/vnd.oai.openapi;version=3.0.0",
          "payload": {
            "type": "object",
            "properties": {
              "counter": {
                "type": "number"
              }
            },
            "required": [
              "counter"
            ]
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EventDto": {
        "type": "object",
        "properties": {
          "counter": {
            "type": "number"
          }
        },
        "required": [
          "counter"
        ]
      }
    }
  }
}

自动化

异步API文档可以通过以下多个步骤来自动化：

  • 分别使用ApiProperty和ApiPropertyOptional装饰器（来自@nestjs/swagger包）定义DTO及其必需的和可选字段，分别为
  • 从定义的DTOS生成OpenAPI文档
  • 从生成的OpenAPI文档中解析和重用组件模式，以构建异步API文档的频道消息和组件模式

验证

使用AsyncAPI Studio验证书面规范。

预览

有多个选项

  • AsyncAPI Studio

  • vscode扩展asyncapi-preview，打开命令调色板，然后运行Preview AsyncAPI命令。

UI世代

  • 安装@asyncapi/cli和对应的模板软件包（例如，@asyncapi/html-template，@asyncapi/markdown-template）
  • 更新软件包。 
{
  "scripts": {
    // ...
    "generate-docs:html": "asyncapi generate fromTemplate ./asyncapi/asyncapi.json @asyncapi/html-template --output ./docs/html",
    "generate-docs:markdown": "asyncapi generate fromTemplate ./asyncapi/asyncapi.json @asyncapi/markdown-template --output ./docs/markdown"
  }
}