asyncapi/github-action-for-cli

AsyncAPI CLI GitHub Action

概述

AsyncAPI CLI GitHub Action是一个专为在GitHub工作流中集成AsyncAPI CLI而设计的工具，允许开发者在CI/CD流程中无缝执行AsyncAPI相关命令，如验证API规范文件、生成文档、代码生成等，从而简化API规范的自动化管理和质量保障。

核心功能与特性

• 完整命令支持：与AsyncAPI CLI深度集成，支持所有官方命令（验证、生成、新建等）
• CI/CD无缝集成：可直接嵌入GitHub工作流，实现代码提交、PR或发布流程中的自动化操作
• 轻量高效：快速启动并执行命令，不增加额外构建负担
• 版本灵活：支持指定AsyncAPI CLI版本，确保环境一致性
• 广泛兼容性：适配各类AsyncAPI文件格式（YAML/JSON）及规范版本

使用场景

• 代码提交验证：在开发者提交代码或创建PR时，自动验证AsyncAPI文件的语法正确性和规范性
• 文档自动生成：定期或触发式生成最新API文档，并部署到静态站点（如GitHub Pages）
• 代码生成自动化：在发布流程中自动生成客户端/服务器代码，并集成到项目构建中
• 规范一致性保障：确保团队所有成员提交的AsyncAPI规范符合项目标准和最佳实践

使用方法与配置说明

前提条件

• 已拥有GitHub仓库，且项目中包含AsyncAPI文件（通常命名为asyncapi.yaml或asyncapi.json）
• 熟悉GitHub Actions工作流配置（即.github/workflows/目录下的YAML文件）

基本配置示例（文件验证）

在GitHub工作流文件中添加以下配置，实现代码提交时自动验证AsyncAPI文件：

yaml
name: Validate AsyncAPI Specification
on: [push, pull_request]

jobs:
  validate-asyncapi:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Validate AsyncAPI file
        uses: asyncapi/cli-github-action@v1  # 使用最新稳定版Action
        with:
          command: validate ./asyncapi.yaml  # 执行验证命令，指定文件路径

文档生成示例

以下配置演示如何自动生成AsyncAPI文档并上传为工作流制品：

yaml
name: Generate AsyncAPI Documentation
on:
  push:
    branches: [ main ]

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Generate documentation
        uses: asyncapi/cli-github-action@v1
        with:
          command: generate docs ./asyncapi.yaml -o ./generated-docs  # 生成文档到指定目录

      - name: Upload documentation artifact
        uses: actions/upload-artifact@v3
        with:
          name: asyncapi-documentation
          path: ./generated-docs

配置参数说明

更多资源

• AsyncAPI CLI完整命令参考：官方文档
• GitHub Action详细指南：AsyncAPI CLI GitHub Action文档
• 问题反馈与贡献：https://github.com/asyncapi/cli