使用 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)，提供程式碼產生服務。

映像檔接受下列 env 變數

JAVA_MEM 例如 1024m
HTTP_PORT 例如 8080
HIDDEN_OPTIONS_PATH (替代 HIDDEN_OPTIONS)：如果附加包含 hiddenOptions.yaml 檔案 (定義要隱藏的語言) 的磁碟區，則很有用。例如 /data/hiddenOptions.yaml
HIDDEN_OPTIONS (替代 HIDDEN_OPTIONS_PATH)：允許以 env 變數的形式傳遞隱藏的選項，格式為 {category}:{language},{language},{language}|{category}:{language},{language},{language} 例如 servers:foo,bar|clientsV3:wtf,isthis，其中 category 可以是 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 下。