Swagger Codegen 项目 Docker 环境使用指南

Swagger Codegen 项目 Docker 环境使用指南

swagger-codegen swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition. 项目地址: https://gitcode.com/gh_mirrors/sw/swagger-codegen

前言

Swagger Codegen 是一个强大的代码生成工具，能够根据 OpenAPI/Swagger 规范自动生成客户端 SDK、服务器存根和 API 文档。本文将详细介绍如何在 Docker 环境中使用和开发 Swagger Codegen 项目，帮助开发者快速搭建开发环境并提高工作效率。

Docker 开发环境搭建

准备工作

在开始之前，请确保您的系统已经安装了 Docker 环境。Docker 提供了一个隔离的容器环境，可以避免本地环境配置的复杂性。

使用 run-in-docker.sh 脚本

Swagger Codegen 项目提供了一个便捷的 run-in-docker.sh 脚本，该脚本会自动处理以下事项：

1. 将本地代码仓库映射到容器内的 /gen 目录
2. 将本地 Maven 仓库 (~/.m2/repository) 映射到容器内的相应位置
3. 提供一致的开发环境

基本使用方法

要执行 Maven 打包命令，只需运行：

./run-in-docker.sh mvn package

构建完成后，生成的构件将出现在您的工作目录中。

作为 CLI 工具使用

构建完成后，run-in-docker.sh 脚本可以直接作为 Swagger Codegen CLI 的入口。使用时需要注意：

• 所有输出目录必须位于 /gen 下（如 /gen/out）
• 生成的代码会自动映射到本地目录

常用命令示例：

# 查看帮助信息
./run-in-docker.sh help

# 查看支持的语言列表
./run-in-docker.sh langs

# 生成 Go 客户端代码
./run-in-docker.sh generate \
    -i modules/swagger-codegen/src/test/resources/2_0/petstore.yaml \
    -l go \
    -o /gen/out/go-petstore \
    -DpackageName=petstore

预构建的 Docker 镜像使用

Swagger Codegen 官方提供了两个预构建的 Docker 镜像，分别适用于不同场景。

Swagger Generator 镜像

这是一个自托管的 Web 应用程序和 API，适用于以下场景：

• 需要将代码生成功能集成到 CI/CD 流水线中
• 需要提供 Web 接口供其他系统调用

使用示例

以下是一个完整的自动化流程示例，包含启动服务、生成代码和清理资源：

# 启动容器并保存容器ID
CID=$(docker run -d -p 8188:8080 swaggerapi/swagger-generator)

# 等待服务启动
sleep 10

# 生成 JavaScript 客户端代码
RESULT=$(curl -X POST \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    -d '{"swaggerUrl": "https://petstore.swagger.io/v2/swagger.json"}' \
    'http://localhost:8188/api/gen/clients/javascript' | jq '.link' | tr -d '"')

# 下载生成的代码
curl -o result.zip "$RESULT"

# 清理容器
docker stop $CID && docker rm $CID

Swagger Codegen CLI 镜像

这是一个独立的命令行工具镜像，适用于：

• 不想在本地安装 Java 环境的开发者
• 需要快速尝试不同版本生成器的场景

使用示例

# 生成 Go 客户端代码到当前目录的 out/go 子目录
docker run --rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli generate \
    -i https://petstore.swagger.io/v2/swagger.json \
    -l go \
    -o /local/out/go

# Windows 用户使用
docker run --rm -v %CD%:/local swaggerapi/swagger-codegen-cli generate \
    -i https://petstore.swagger.io/v2/swagger.json \
    -l go \
    -o /local/out/go

高级使用技巧

自定义生成器开发

对于需要开发自定义生成器的用户，建议在 Docker 环境中进行开发，这样可以确保环境一致性。开发流程与常规开发类似，但所有操作都通过 run-in-docker.sh 脚本执行。

性能优化建议

1. Maven 仓库缓存：run-in-docker.sh 已经自动映射了本地 Maven 仓库，避免重复下载依赖
2. 批量生成：在容器内一次性执行多个生成命令，减少容器启动开销
3. 资源限制：对于大型项目，可以适当增加 Docker 容器的内存限制

常见问题解答

Q: 为什么生成的代码没有出现在本地目录？ A: 请确保输出目录以 /gen 开头，这是容器内到本地目录的映射点。

Q: 如何指定特定版本的生成器？ A: 在使用预构建镜像时，可以通过指定镜像标签来选择版本，如 swaggerapi/swagger-codegen-cli:2.4.0

Q: 能否在生成时使用自定义模板？ A: 可以，将模板目录映射到容器内，然后通过 -t 参数指定模板路径

总结

通过 Docker 使用 Swagger Codegen 可以极大简化环境配置工作，提供一致的开发体验。无论是进行常规的代码生成，还是开发自定义生成器，Docker 都是一个值得推荐的选择。本文介绍的方法涵盖了从基础使用到高级场景的各种技巧，希望能帮助您更高效地使用 Swagger Codegen 项目。

swagger-codegen swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition. 项目地址: https://gitcode.com/gh_mirrors/sw/swagger-codegen