使用 Docker 的 Swagger Codegen

在 Docker 中开发

您可以使用 run-in-docker.sh 来完成所有开发。此脚本将您的本地存储库映射到 Docker 容器中的 /gen。它还将 ~/.m2/repository 映射到相应的容器位置。

要执行 mvn package

1
git clone https://github.com/swagger-api/swagger-codegen
2
cd swagger-codegen
3
./run-in-docker.sh mvn package

现在可以在您的工作目录中访问构建工件。

构建完成后，run-in-docker.sh 将充当 swagger-codegen-cli 的可执行文件。要生成代码，您需要输出到 /gen 下的目录（例如 /gen/out）。例如

1
./run-in-docker.sh help # Executes 'help' command for swagger-codegen-cli
2
./run-in-docker.sh langs # Executes 'langs' command for swagger-codegen-cli
3
./run-in-docker.sh /gen/bin/go-petstore.sh  # Builds the Go client
4
./run-in-docker.sh generate -i modules/swagger-codegen/src/test/resources/2_0/petstore.yaml \
5
    -l go -o /gen/out/go-petstore -DpackageName=petstore # generates go client, outputs locally to ./out/go-petstore

在 Docker 中进行独立生成器开发

请参阅独立生成器开发

在 Vagrant 中运行 Docker

先决条件：安装 Vagrant 和 VirtualBox。

1
git clone http://github.com/swagger-api/swagger-codegen.git
2
cd swagger-codegen
3
vagrant up
4
vagrant ssh
5
cd /vagrant
6
./run-in-docker.sh mvn package

公共预构建 Docker 镜像

Swagger 生成器 Docker 镜像

Swagger 生成器镜像提供了一个随时可用的 Web 应用程序 (swagger-generator)，提供代码生成服务。

镜像接受以下环境变量

JAVA_MEM，例如 1024m
HTTP_PORT，例如 8080
HIDDEN_OPTIONS_PATH（HIDDEN_OPTIONS 的替代方案）：如果附加包含 hiddenOptions.yaml 文件的卷，该文件定义要隐藏哪些语言，则非常有用。例如 /data/hiddenOptions.yaml
HIDDEN_OPTIONS（HIDDEN_OPTIONS_PATH 的替代方案）：允许以 {category}:{language},{language},{language}|{category}:{language},{language},{language} 格式将隐藏选项作为环境变量传递，例如 servers:foo,bar|clientsV3:wtf,isthis，其中类别可以是 clients、servers、clientsV3、serversV3

运行容器的示例

docker pull swaggerapi/swagger-generator-v3

docker run -e "HIDDEN_OPTIONS=servers:foo,bar|clientsV3:fgf,sdsd" -e "JAVA_MEM=1024m" -e "HTTP_PORT=80" -p 80:80 --name swagger-generator-v3 -v /tmp:/jetty_home/lib/shared swaggerapi/swagger-generator-v3

或

docker run -e "HIDDEN_OPTIONS_PATH=/hiddenOptions.yaml" -e "JAVA_MEM=1024m" -e "HTTP_PORT=80" -p 80:80 --name swagger-generator-v3 -v /tmp:/jetty_home/lib/shared swaggerapi/swagger-generator-v3

此 Docker 镜像通过将生成器 jar 放入 /jetty_home/lib/shared 目录（通常通过 Docker 卷）来支持自定义生成器；例如，在主机上拥有 /my/custom/coolgenerator.jar 和 /my/custom/weirdgenerator.jar，以下命令会将它们添加到生成器服务生成器中

docker run -e "HIDDEN_OPTIONS_PATH=/hiddenOptions.yaml" -e "JAVA_MEM=1024m" -e "HTTP_PORT=80" -p 80:80 --name swagger-generator-v3 -v /my/custom:/jetty_home/lib/shared swaggerapi/swagger-generator-v3

请注意，在 3.0.20 版本之前，即使不使用自定义生成器，也需要提供 -v /{WHATEVER_DIR}:/jetty_home/lib/shared。

另请参阅在线生成器。

Swagger 生成器“最小”Docker 镜像

Swagger 生成器“最小”镜像可以用作自托管的 Web 应用程序和 API 来生成代码。

此容器可以集成到 CI 管道中，并且需要一些 Docker 编排才能访问生成的代码。

用法示例

1
# Start container and save the container id
2
CID=$(docker run -d swaggerapi/swagger-generator-v3-minimal)
3
# allow for startup
4
sleep 5
5
# Get the IP of the running container
6
GEN_IP=$(docker inspect --format '{{.NetworkSettings.IPAddress}}'  $CID)
7
# Execute an HTTP request and store the download link
8
curl -X POST \
9
           https://127.0.0.1:8080/api/generate \
10
           -H 'content-type: application/json' \
11
           -d '{
12
           "specURL" : "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml",
13
           "lang" : "jaxrs-jersey",
14
           "type" : "SERVER",
15
           "codegenVersion" : "V3"
16
         }' > result.zip
17
# Shutdown the swagger generator image
18
docker stop $CID && docker rm $CID

在上面的示例中，result.zip 将包含生成的客户端。

另请参阅在线生成器。

Swagger Codegen CLI Docker 镜像

Swagger Codegen 镜像充当独立的可执行文件。它可以作为通过 Homebrew 安装的替代方案，或者适用于无法安装 Java 或升级已安装版本的开发人员。

要使用此镜像生成代码，您需要将本地位置挂载为卷。

示例

1
docker run --rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli-v3 generate \
2
    -i http://petstore.swagger.io/v2/swagger.json \
3
    -l go \
4
    -o /local/out/go

生成的代码将位于当前目录下的 ./out/go 中。