Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
swagger-codegen contains a template-driven engine to generate client code in different languages by parsing your Swagger Resource Declaration.
Scala Shell ActionScript Objective-C CSS

This branch is 2 commits ahead, 451 commits behind swagger-api:master

merged #38

latest commit 09eadd82c4
@fehguy authored
Failed to load latest commit information.
bin more lenient Version.scala
distro update to sbt 0.12.2
samples Issue 244 - checkout on windows fails due to special chars
src merged #38
.gitignore created CSharp codegen templating
.travis.yml Update .travis.yml
LICENSE Create LICENSE Fix typo in
build.sbt set version to 2.10.4
package.json added yml2swagger
sbt fix for #156

Swagger Code Generator

Build Status


This is the swagger codegen project, which allows generation of client libraries automatically from a Swagger-compliant server.

What's Swagger?

The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, Swagger removes the guesswork in calling the service.

Check out Swagger-Spec for additional information about the Swagger project, including additional libraries with support for other languages and more.


You need the following installed and available in your $PATH:

Note! Some folks have had issues with OOM errors with java version "1.6.0_51". It's strongly suggested that you upgrade to 1.7!

You also need to add the scala binary to your PATH.

After cloning the project, you need to build it from source with this command:

./sbt assembly

or for Windows...

sbt assembly

To generate a sample client library

You can build a client against Wordnik's petstore API as follows:


This will run the script in samples/client/petstore/ScalaPetstoreCodegen.scala and create the client. You can then compile and run the client, as well as unit tests against it:

cd samples/client/petstore/scala
mvn package

Other languages have petstore samples, too:


Generating libraries from your server

It's just as easy--you can either run the default generators:

./bin/ com.wordnik.swagger.codegen.BasicScalaGenerator special-key

Replace Scala with Flash, Java, Objc, PHP, Python, Python3, Ruby.

You will probably want to override some of the defaults--like packages, etc. For doing this, just create a scala script with the overrides you want. Follow ScalaPetstoreCodegen as an example:

For example, create src/main/scala/MyCodegen.scala with these contents:

import com.wordnik.swagger.codegen.BasicScalaGenerator

object MyCodegen extends BasicScalaGenerator {
  def main(args: Array[String]) = generateClient(args)

  // location of templates
  override def templateDir = "scala"

  // where to write generated code
  override def destinationDir = "client/scala/src/main/scala"

  // api invoker package
  override def invokerPackage = "com.myapi.client"

  // package for models
  override def modelPackage = Some("com.myapi.client.model")

  // package for api classes
  override def apiPackage = Some("com.myapi.client.api")

  // supporting classes
  override def supportingFiles = List(
    ("apiInvoker.mustache", destinationDir + + packageName.replaceAll("\\.",, "ApiInvoker.scala"),
    ("pom.mustache", destinationDir, "pom.xml")

Now you can generate your client like this:

./bin/ src/main/scala/MyCodegen.scala super-secret-key

w00t! Thanks to the scala interpretor, you didn't even need to recompile.

Modifying the client library format

Don't like the default swagger client syntax? Want a different language supported? No problem! Swagger codegen processes mustache templates with the scalate engine. You can modify our templates or make your own.

You can look at src/main/resources/${your-language} for examples. To make your own templates, create your own files and override the templateDir in your script to point to the right place. It actually is that easy.

Where is Javascript???

See our javascript library--it's completely dynamic and doesn't require static code generation. There is a third-party component called swagger-js-codegen that can generate angularjs or nodejs source code from a swagger specification.

Generating a client from flat files (i.e. no remote server calls)

If you don't want to call your server, you can save the swagger spec files into a directory and pass an argument to the code generator like this:


Or for example:


Which simple passes -DfileMap=src/test/resources/petstore as an argument. Great for creating libraries on your ci server... or while coding on an airplane.

Validating your swagger spec

You can use the validation tool to see that your server is creating a proper spec file. If you want to learn more about the spec file and format, please see swagger-core. This tool will read the server and generate a report of any violations of the spec. If there are violations, the client codegen and ui may not work correctly.

To validate an api and write output to ./swagger-errors.html:

./bin/ "specia-key" ./swagger-errors.html

Generating static api documentation

If you need to make static pages or don't want the sandbox of the swagger-ui, you can use the codegen to build them. Remember, the engine is just using mustache templates--the output format is your call.


Will produce the output here:

which is based on these templates:

and looks like this


To build a server stub

You can also use the codegen to generate a server for a couple different frameworks. Take a look here:

Migrating from Swagger 1.1 to 1.2 format

If you've spent time hand-crafting your swagger spec files, you can use the SpecConverter to do the dirty work. For example:

$ ./bin/ wordnik-developer
writing file wordnik-developer/api-docs
writing file wordnik-developer/account
writing file wordnik-developer/word
writing file wordnik-developer/words
writing file wordnik-developer/wordList
writing file wordnik-developer/wordLists

Will read the 1.1 spec from wordnik developer and write it into the folder called wordnik-developer.

To build the codegen library

This will create the swagger-codegen library from source.

./sbt assembly

Note! The templates are included in the library generated. If you want to modify the templates, you'll need to either repackage the library OR modify your codegen script to use a file path!


Copyright 2014 Wordnik, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Something went wrong with that request. Please try again.