How do I use the public swagger-generator docker image to generate a client?

Question

We have a fully dockerized web app with a valid Swagger definition for the API. The API runs in its own docker container, and we're using docker-compose to orchestrate everything. I want to generate a Ruby client based on the Swagger definition located at http://api:8443/apidocs.json.

I've poured through the documentation here, which led me to Swagger's public docker image for generating client and server code. Sadly the documentation is lacking and offers no examples for actually generating a client with the docker image.

The Dockerfile indicates its container runs a web service, which I can only assume is the dockerized version of http://generator.swagger.io. As such, I would expect to be able to generate a client with the following command:

curl -X POST -H "content-type:application/json" -d \ '{"swaggerUrl":"http://api:8443/apidocs"}' \ http://swagger-generator:8080/api/gen/clients/ruby

No luck here. I keep getting "invalid swagger definition" even though I've confirmed the swagger definition is valid with (npm -q install -g swagger-tools >/dev/null) && swagger-tools validate http://api:8443/apidocs.

Any ideas?

Answer 1

indeed you are correct, the docker image you're referring to is the same image used at http://generator.swagger.io

The issue you're having is the input parameter isn't correct.

Now to get it right, please note that the swagger-generator has a web interface. So once you start it up, like the instructions say, open it in a browser. For example (replace the GENERATOR_HOST with your machine's IP address):

docker run -d -e GENERATOR_HOST=http://192.168.99.100 -p 80:8080 swaggerapi/swagger-generator

then you can open the swagger-ui on http://192.168.99.100

The important part here is that you can use the UI to see the call syntax. If you're generating a client, go to http://192.168.99.100/#!/clients/generateClient select the language you want to generate and click the payload on the right. Replace the swaggerUrl field with the address of your server and voila.

You can use the output in the curl to figure out how to call from the command line. It should be easy from there.

Please keep in mind that just because a 3rd party tool says the swagger definition is valid doesn't mean it actually is. I don't think that's your issue, though, but 3rd party tool mileage may vary...