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](https://github.com/swagger-api/swagger-spec) for additional information about the Swagger project, including additional libraries with support for other languages and more.
The Swagger Specification has undergone 3 revisions since initial creation in 2010. The swagger-codegen project has the following compatibilies with the swagger specification:
Swagger Codegen Version | Release Date | Swagger Spec compatability | Notes
Don't like the default swagger client syntax? Want a different language supported? No problem! Swagger codegen processes mustache templates with the [jmustache](https://github.com/samskivert/jmustache) 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 use the `-t` flag to specify your tempalte folder. It actually is that easy.
There is a third-party component called [swagger-js-codegen](https://github.com/wcandillon/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
There are different aspects of customizing the code generator beyond just creating or modifying templates. Each language has a supporting configuration file to handle different type mappings, etc:
```
$ ls -1 src/main/java/com/wordnik/swagger/codegen/languages/
AndroidClientCodegen.java
JavaClientCodegen.java
JaxRSServerCodegen.java
ObjcClientCodegen.java
StaticDocCodegen.java
```
Each of these files creates reasonable defaults so you can get running quickly. But if you want to configure package names, prefixes, model folders, etc., you may want to extend these.
To change, for example, the prefix for the Objective-C generated files, simply subclass the ObjcClientCodegen.java:
```
package com.mycompany.swagger.codegen;
import com.wordnik.swagger.codegen.languages.*;
public class MyObjcCodegen extends ObjcClientCodegen {
static {
PREFIX = "HELO";
}
}
```
and specify the `classname` when running the generator:
```
-i com.mycompany.swagger.codegen.MyObjcCodegen
```
Your subclass will now be loaded and overrides the `PREFIX` value in the superclass.
You have options. The easiest is to use our [online validator](https://github.com/swagger-api/validator-badge) which not only will let you validate your spec, but with the debug flag, you can see what's wrong with your spec. For example:
To do so, just use the `-l dynamic-html` flag when reading a spec file. This creates HTML documentation that is available as a single-page application with AJAX. To view the documentation:
```
cd samples/swagger-dynamic-html/
npm install
node .
```
Which launches a node.js server so the AJAX calls have a place to go.
### Generating static html api documentation
To do so, just use the `-l html` flag when reading a spec file. This creates a single, simple HTML file with embedded css so you can ship it as an email attachment, or load it from your filesystem:
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 specify a path to your scripts
