如何在SwaggerHub自动更新API文档？.NET Core+GitHub自动化方案咨询

步骤1：准备SwaggerHub凭据与文档信息 #

• 在SwaggerHub个人设置中生成API密钥，将其添加到GitHub仓库的Secrets中，命名为SWAGGERHUB_API_KEY
• 记录SwaggerHub目标文档的三个关键信息：文档所有者（owner）、API名称、版本号

步骤2：配置GitHub Actions工作流 #

在项目根目录创建.github/workflows/swaggerhub-update.yml文件，写入以下内容（根据实际情况替换占位符）：

name: Auto Update SwaggerHub Docs
on:
  push:
    branches: [ main ] # 替换为你需要触发自动更新的分支

jobs:
  sync-swagger:
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4

      - name: 配置.NET环境
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x' # 替换为你的项目.NET版本

      - name: 构建项目
        run: dotnet build --configuration Release

      - name: 导出Swagger JSON文档
        # 无需启动项目，直接从编译后的程序集导出Swagger文档
        run: dotnet swagger tofile --output swagger.json bin/Release/net8.0/YourProject.dll v1
        # 替换：YourProject.dll为你的项目程序集名称，v1为Swagger文档版本

      - name: 更新SwaggerHub文档
        run: |
          curl -X PUT "https://api.swaggerhub.com/apis/{OWNER}/{API_NAME}/{VERSION}" \
          -H "Authorization: Bearer ${{ secrets.SWAGGERHUB_API_KEY }}" \
          -H "Content-Type: application/json" \
          -d @swagger.json
        # 替换占位符：{OWNER}、{API_NAME}、{VERSION}为你的SwaggerHub文档信息

关键注意事项 #

• 如果项目未安装Swashbuckle.AspNetCore.Cli工具，需在项目文件（.csproj）中添加以下引用：

  <ItemGroup>
    <DotNetCliToolReference Include="Swashbuckle.AspNetCore.Cli" Version="6.4.0" />
  </ItemGroup>
  

  或全局安装工具：dotnet tool install -g Swashbuckle.AspNetCore.Cli
• 若导出的是YAML格式文档，需调整dotnet swagger命令的输出后缀为.yaml，并修改curl请求的Content-Type为application/yaml
• 确保GitHub仓库的Secrets中已正确添加SWAGGERHUB_API_KEY，且该密钥拥有SwaggerHub文档的编辑权限

内容的提问来源于stack exchange，提问作者Srikanth