在 Debian 上使用 Swagger Codegen 的完整指南
一 准备环境
- 安装 Java 11（Swagger Codegen 2.x 基于 Java）：sudo apt update && sudo apt install -y openjdk-11-jdk。
- 可选：安装 git 与 maven（便于拉取依赖或自行构建，非必须）：sudo apt install -y git maven。
- 验证环境：java -version 应显示 11.x。
二 安装与准备规范文件
- 下载 Swagger Codegen CLI 2.4.21（稳定版）：
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。
- 准备 API 规范文件（支持 OpenAPI/Swagger YAML 或 JSON），例如 swagger.yaml。
三 生成代码
- 基本用法（以生成 Java 客户端为例）：
java -jar swagger-codegen-cli.jar generate -i /path/to/api-spec.yaml -l java -o /path/to/output/dir。
- 常用选项：
- -i 指定规范文件路径（YAML/JSON）。
- -l 指定语言（如 java、python、javascript 等）。
- -o 指定输出目录。
- 可通过配置文件自定义包名、API 包、模型包等参数。
四 便捷使用与自动化
- 全局命令封装（将 CLI 放入 PATH）：
sudo install swagger-codegen-cli.jar /usr/local/bin/swagger，之后可直接执行：
swagger generate client -i swagger.yaml -l java -o ./client。
- 一键脚本示例 generate-swagger.sh：
#!/bin/bash
API_SPEC=“/path/to/api-spec.yaml”
OUTPUT_DIR=“./generated”
JAR=“swagger-codegen-cli-2.4.21.jar”
[ ! -f “$JAR” ] && wget https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.21/$JAR
java -jar $JAR generate -i $API_SPEC -l java -o $OUTPUT_DIR
赋权并运行：chmod +x generate-swagger.sh && ./generate-swagger.sh。
五 常见问题与替代方案
- 多版本管理建议：在规范中使用不同的 路径前缀（如 /api/v1、/api/v2） 或 info.version 区分版本，并为每个版本单独生成代码与文档。
- 展示与测试：如需在浏览器查看文档，可部署 Swagger UI 并指向你的规范文件或生成的服务。
- 其他安装方式：也可通过 Docker 快速运行 Swagger UI（便于演示与测试）：
sudo apt install -y docker.io
docker pull swaggerapi/swagger-ui-express
docker run -p 8080:8080 swaggerapi/swagger-ui-express
访问：http://localhost:8080。
- 注意区分工具链：swagger-codegen（Java CLI，本文所用）与 openapi-generator（社区更活跃，命令与参数略有差异），两者用法相似但不可混用配置。