lmazuel/swagger-to-sdk

SwaggerToSDK Docker镜像

镜像概述

该Docker镜像封装了SwaggerToSDK自动化脚本，用于在Swagger文件每次提交时执行以下操作：

• 针对SDK语言进行兼容性测试
• 自动为各语言SDK生成拉取请求（PR）

此镜像仅支持Python 3.6环境，项目仍在开发中且迭代较快，我们会尽力保持文档更新。

核心功能

1. SDK语言测试：验证Swagger转换后的SDK代码在目标语言中的可用性
2. 自动化PR生成：在SDK仓库中自动创建PR，同步Swagger更新到SDK代码

使用场景

• 开发团队需从Swagger API定义自动生成多语言SDK
• 持续集成（CI）流程中，需自动化同步Swagger变更到SDK仓库
• 统一管理Swagger到SDK转换配置的项目

配置说明

需在目标仓库根目录放置swagger_to_sdk.json配置文件，示例如下：

json
{
  "$schema": "https://raw.githubusercontent.com/lmazuel/swagger-to-sdk/master/swagger_to_sdk_config.schema.json",
  "meta": {
    "after_scripts": [
      "gofmt -w ./services/"
    ],
    "version":"0.2.0",
    "autorest_options": {
      "license-header": "MICROSOFT_MIT_NO_VERSION",
      "payload-flattening-threshold": 2,
      "python": "",
      "azure-arm": true,
      "sdkrel:python-sdks-folder": "."
    },
    "envs": {
      "sdkrel:SCRIPTPATH": "./scripts"
    },    
    "advanced_options": {
      "clone_dir": "./src/github.com/Azure/azure-sdk-for-go"
    },    
    "wrapper_filesOrDirs": [],
    "delete_filesOrDirs": [
      "credentials.py",
      "exceptions.py"
    ],
    "generated_relative_base_directory": "*client"
  },
  "projects": {
    "authorization": {
      "autorest_options": {
        "input-file": "arm-authorization/2015-07-01/swagger/authorization.json",
        "namespace": "azure.mgmt.authorization",
        "package-version": "0.30.0"
      },
      "output_dir": "azure-mgmt-authorization/azure/mgmt/authorization",
      "build_dir": "azure-mgmt-authorization"
    },
    "recoveryservicesbackup": {
      "markdown": "arm-recoveryservicesbackup/readme.md",
      "generated_relative_base_directory": "Generated/Python/azure/mgmt/recoveryservicesbackup",
      "output_dir":  "azure-mgmt-recoveryservicesbackup/azure/mgmt/recoveryservicesbackup",
      "build_dir": "azure-mgmt-recoveryservicesbackup"
    }    
  }
}

Meta配置

• version：配置文件版本必须为0.2.0
• after_scripts：生成完成后执行的命令列表，按顺序执行，工作目录为克隆路径
• autorest_options：传递给Autorest的全局选项，可被项目级配置覆盖（无法覆盖--output-folder）；前缀sdkrel:的选项为相对路径，会解析为SDK文件夹路径
• envs：after_scripts的环境变量；前缀sdkrel:的选项为相对路径，会解析为SDK文件夹路径
• advanced_options：高级选项，如clone_dir（克隆仓库的额外目录层，适用于Go项目）
• wrapper_filesOrDirs：生成SDK时保留的文件/目录列表，支持Bash通配符
• delete_filesOrDirs：生成SDK时删除的文件/目录列表，支持Bash通配符
• generated_relative_base_directory：Autorest生成文件的相对基础目录（在delete_filesOrDirs前应用）

Projects配置

键为项目ID（建议使用命名空间风格，如datalake.store.account），值包含：

• markdown：Autorest MD文件路径（相对于rest-folder参数）
• autorest_options：项目级Autorest选项，覆盖全局meta配置
• wrapper_filesOrDirs：项目级保留文件/目录列表（追加到meta配置）
• delete_filesOrDirs：项目级删除文件/目录列表（追加到meta配置）
• generated_relative_base_directory：项目级生成文件基础目录（覆盖meta配置）
• output_dir：SDK仓库中存放生成文件的目录
• build_dir：存放生成元数据（Autorest版本、生成日期等）的目录，需唯一避免覆盖

部署示例

Docker Run命令

将本地仓库目录挂载到容器工作空间，执行脚本：

bash
docker run -v /path/to/your/repo:/workspace docker.xuanyuan.run/lmazuel/swagger-to-sdk

Docker Compose示例

创建docker-compose.yml：

yaml
version: '3'
services:
  swagger-to-sdk:
    image: docker.xuanyuan.run/lmazuel/swagger-to-sdk
    volumes:
      - ./your-repo:/workspace

执行：docker-compose up