Client-side code generation

gatebuzz

An incredibly powerful feature of Swagger documentation is the ability to generate not just human readable live docs - https://developer.oxforddictionaries.com/documentation - but also all the code needed to talk to an API.

You will need at least Java 7 to run through this exercise.

Note: This full example is also available from my Github - https://github.com/psh/oxford-dictionary-api-code-gen - clone the repo and steps 1 -5 will already be done for you.

1. Download the Swagger code generation tool

At the time of writing this, swagger-codegen is at version 2.2.1 and can be obtained from http://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.2.1/swagger-codegen-cli-2.2.1.jar

2. Create a working directory

Create a working directory and copy the swagger-codegen-cli-2.2.1.jar into it. I am lazy, so I also renamed it to "swagger-codegen.jar" to save typing.

3. Check everything is ready to go

Check out the help built into Swagger codegen by typing

java -jar swagger-codegen.jar help

You should see a helpful message telling you about the options you have available. If you need a deeper-dive into Swagger codegen documentation, take a look at http://swagger.io/swagger-codegen/

4. Create an "output" directory

Swagger needs somewhere to place the generated client code and things just get messy if you generate 150 source files into the current directory!

5. Create a configuration file

For this example, I will generate a Java client to talk to the Oxford Dictionary API. The tool supports dozens of other languages and frameworks - take a look at the list by running

java -jar swagger-codegen.jar langs

The fictional project I am creating uses Retrofit v2 and RxJava, so my configuration file ("config.json") for Swagger will look like this:

{ "sourceFolder": "src", "modelPackage": "com.gatebuzz.oxford.model", "apiPackage": "com.gatebuzz.oxford.api", "library": "retrofit2", "useRxJava": true }

6. Run Swagger Codegen

I need to tell Swagger to

• Generate a Java client
• Configure itself from "config.json"
• Read the Oxford Dictionary API docs
• Write to the "output" directory I created

The command line is a little long, but looks like this (note: line continuation "\" characters have been inserted to aid clarity.)

java -jar swagger-codegen.jar generate \ --lang java \ -c config.json \ -o output \ -i https://developer.oxforddictionaries.com/swagger/spec/public_doc_guest.json

The tool is quite chatty as its reading files and creating code. When its finished you will have a working project in the "output" directory!

Simone

Hi @gatebuzz !
Many thanks for this, it will certainly be useful for a lot of people - it's great that you made it so clear.
I'm making it sticky on the top of the discussion list.

vantipin

Hi @gatebuzz,
Thanks for pointing out link to swagger spec in your manual. We probably should add it to portal documentation.
Anyway, a nice manual for Java developers.

gatebuzz

Yes, the code generation tool uses Java, but the output can be any one of the available languages:

$ java -jar swagger-codegen.jar langs

Available languages: [android, aspnet5, async-scala, cwiki, 
csharp, cpprest, dart, flash, python-flask, go, groovy, java, 
jaxrs, jaxrs-cxf, jaxrs-resteasy, jaxrs-spec, inflector, javascript, 
javascript-closure-angular, jmeter, nancyfx, nodejs-server, 
objc, perl, php, python, qt5cpp, ruby, scala, scalatra, silex-PHP, 
sinatra, rails5, slim, spring, dynamic-html, html, html2, 
swagger, swagger-yaml, swift, tizen, typescript-angular2, 
typescript-angular, typescript-node, typescript-fetch, 
akka-scala, CsharpDotNet2, clojure, haskell, lumen, 
go-server]

It's one of the big benefits of providing us Swagger docs!