apaleo/swagger-codegen

Swagger Codegen镜像

镜像概述

Swagger Codegen是一个模板驱动的工具，基于OpenAPI规范（原Swagger规范）自动生成API客户端库、服务端存根、API文档及配置文件。镜像分为2.X（支持OpenAPI 2.0）和3.X（支持OpenAPI 3.0及2.0转换）版本线，覆盖数十种开发语言与框架，适用于API全生命周期管理。

核心功能

• 多语言客户端生成：支持Java、Python、Go、C#、Ruby等语言及Retrofit、Spring等框架的客户端代码。
• 服务端存根生成：提供ASP.NET Core、Spring Boot、Flask等服务端框架的代码骨架。
• 文档自动化：生成HTML、Confluence Wiki格式的API文档，确保与接口定义同步。
• 配置文件生成：支持Apache2等服务器配置文件生成。
• 规范兼容：2.X支持OpenAPI 2.0，3.X支持OpenAPI 3.0及2.0规范转换。

使用场景

1. API开发加速：通过规范自动生成代码，减少重复编码工作。
2. 团队协作：为跨语言团队生成对应客户端，降低对接成本。
3. CI/CD集成：在持续集成流程中自动更新代码，保证接口一致性。
4. 文档维护：同步生成API文档，避免手动更新导致的不一致。

配置说明

可通过命令行参数定制生成逻辑，关键参数包括：

• -i：指定OpenAPI规范文件路径或URL。
• -l：选择生成的语言/框架（如java、go、python）。
• -o：设置输出目录。
• -c：使用配置文件自定义生成规则（如包名、类名前缀）。

Docker部署示例

1. CLI镜像生成客户端代码

bash
# 生成Go语言客户端（基于Petstore示例API）
docker run --rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l go \
  -o /local/out/go-petstore

（Windows系统替换${PWD}为%CD%）

2. Web服务镜像生成代码

bash
# 启动Swagger Generator服务
CID=$(docker run -d -p 8188:8188 swaggerapi/swagger-generator)
sleep 5 # 等待服务初始化

# 请求生成JavaScript客户端
RESULT=$(curl -X POST --header 'Content-Type: application/json' \
  -d '{"swaggerUrl":"[***]"}' \
  'http://localhost:8188/api/gen/clients/javascript' | jq '.link' | tr -d '"')

# 下载代码包
curl $RESULT > javascript-client.zip

# 停止容器
docker stop $CID && docker rm $CID