如何在Debian上使用Swagger Codegen

在 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（社区更活跃，命令与参数略有差异），两者用法相似但不可混用配置。