在 Debian 上生成 API 客户端代码
一 准备环境
- 安装 Java 8+（Swagger Codegen 2.x 为 Java 应用）：sudo apt update && sudo apt install -y openjdk-11-jdk。
- 准备 API 规范文件（支持 JSON/YAML，可为本地文件或远程 URL）。
- 说明：在 Debian 上，常见的两条路径是使用 Swagger Codegen CLI（Java） 或 swagger-codegen（npm 包） 来生成客户端代码。
二 方式一 使用 Swagger Codegen CLI 生成客户端
- 下载 CLI（2.4.x 稳定版）：
wget https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.21/swagger-codegen-cli-2.4.21.jar -O swagger-codegen-cli.jar
- 生成代码（示例为 Python 客户端）：
java -jar swagger-codegen-cli.jar generate
-i /path/to/your/swagger.yaml
-l python
-o /path/to/output/python-client
- 常用命令：
- 查看可用语言：java -jar swagger-codegen-cli.jar langs
- 查看某语言可配置项：java -jar swagger-codegen-cli.jar config-help -l java
- 验证规范：java -jar swagger-codegen-cli.jar validate -i /path/to/spec.yaml
- 说明：CLI 支持从本地或远程规范生成多语言客户端，适合在 CI/CD 中脚本化调用。
三 方式二 使用 npm 的 swagger-codegen 生成客户端
- 安装 Node.js 与 npm：sudo apt install -y nodejs npm
- 全局安装 swagger-codegen：sudo npm install -g swagger-codegen
- 生成代码（示例为 JavaScript 客户端）：
swagger-codegen generate -i /path/to/your/swagger.yaml -l javascript -o /path/to/output/js-client
- 说明：适合偏好 npm/JavaScript 工作流的场景，命令与 CLI 类似。
四 常用示例与参数
- 生成 Java 客户端：
java -jar swagger-codegen-cli.jar generate -i spec.yaml -l java -o ./client-java
- 生成 PHP 客户端：
java -jar swagger-codegen-cli.jar generate -i spec.yaml -l php -o ./client-php
- 生成 Spring 服务端存根（如需要）：
java -jar swagger-codegen-cli.jar generate -i spec.yaml -l spring -o ./server-spring
- 提示：使用 -c config.json 传入语言专属配置（如包名、日期类型等），可用 config-help -l <语言> 查看可配置项。
五 在 Debian 上的自动化与集成
- 将生成步骤写入脚本（示例 generate-client.sh）：
#!/usr/bin/env bash
set -e
SPEC=$1; OUT=$2; LANG=$3
wget -q https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.21/swagger-codegen-cli-2.4.21.jar -O codegen.jar
java -jar codegen.jar generate -i “$SPEC” -l “$LANG” -o “$OUT”
echo “Generated $LANG client in $OUT”
- 在 GitLab CI / GitHub Actions 中调用该脚本即可实现按提交自动生成客户端。
- 安全建议：仅对可信的 OpenAPI/Swagger 规范执行代码生成，避免潜在的代码注入风险。
