Client-side code generation
Categories
- 326 All Categories
- 3 Language datasets
- 9 News and updates
- 18 API endpoints
- 15 Review my code
- 6 Tutorials and presentations
- 92 Frequently asked questions
- 5 How to get useful technical help
- 2 Member guidelines
- 12 Suggest an improvement
- 58 Report a bug
- 10 Ask the Community: Other
- 56 Ask the Community: Technical and operational questions
- 62 General
Client-side code generation
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!
Comments
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.
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.
Yes, the code generation tool uses Java, but the output can be any one of the available languages:
It's one of the big benefits of providing us Swagger docs!