You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is the swagger codegen project, which allows generation of client libraries automatically from a
7
-
Swagger-compliant server.
6
+
This is the swagger codegen project, which allows generation of client libraries automatically from a Swagger-compliant server.
8
7
9
8
## What's Swagger?
10
9
@@ -14,128 +13,85 @@ The goal of Swagger™ is to define a standard, language-agnostic interface to R
14
13
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.
15
14
16
15
17
-
## Compatibility
18
-
The Swagger Specification has undergone 3 revisions since initial creation in 2010. Compatibility between swagger-codegen and the Swagger specification is as follows:
16
+
## Compatability
17
+
The Swagger Specification has undergone 3 revisions since initial creation in 2010. The swagger-codegen project has the following compatibilies with the swagger specification:
19
18
20
-
Swagger Codegen Version | Release Date | Swagger Spec compatibility | Notes
19
+
Swagger Codegen Version | Release Date | Swagger Spec compatability | Notes
With a number of options. You can get the options with the -h flag:
60
56
```
57
+
usage: Codegen
58
+
-a,--auth addes authorization headers when fetching the
59
+
swagger definitions remotely. Pass in a
60
+
URL-encoded string of name:header with a comma
61
+
separating multiple values
62
+
-d,--debug-info prints additional info for debugging
63
+
-h,--help shows this message
64
+
-i,--input-spec <arg> location of the swagger spec, as URL or file
65
+
-l,--lang <arg> client language to generate.
66
+
Available languages include:
67
+
[android, java, jaxrs, nodejs, objc, scalatra,
68
+
scala, dynamic-html, html, swagger, tizen, php,
69
+
python]
70
+
-o,--output <arg> where to write the generated files
71
+
-t,--template-dir <arg> folder containing the template files
72
+
```
61
73
62
-
This will run the script in [samples/client/petstore/ScalaPetstoreCodegen.scala](https://github.com/swagger-api/swagger-codegen/blob/master/samples/client/petstore/scala/ScalaPetstoreCodegen.scala) and create the client. You can then
63
-
compile and run the client, as well as unit tests against it:
74
+
You can then compile and run the client, as well as unit tests against it:
64
75
65
76
```
66
-
cd samples/client/petstore/scala
77
+
cd samples/client/petstore/java
67
78
mvn package
68
79
```
69
80
70
81
Other languages have petstore samples, too:
71
82
```
72
-
./bin/flash-petstore.sh
83
+
./bin/android-petstore.sh
73
84
./bin/java-petstore.sh
74
85
./bin/objc-petstore.sh
75
-
./bin/php-petstore.sh
76
-
./bin/python-petstore.sh
77
-
./bin/python3-petstore.sh
78
-
./bin/ruby-petstore.sh
79
86
```
80
87
81
88
### Generating libraries from your server
82
-
It's just as easy--you can either run the default generators:
Replace `Scala` with `Flash`, `Java`, `Objc`, `PHP`, `Python`, `Python3`, `Ruby`.
89
-
90
-
You will probably want to override some of the defaults--like packages, etc. For doing this, just create a scala
91
-
script with the overrides you want. Follow [ScalaPetstoreCodegen](https://github.com/swagger-api/swagger-codegen/blob/master/samples/client/petstore/scala/ScalaPetstoreCodegen.scala) as an example:
92
-
93
-
For example, create `src/main/scala/MyCodegen.scala` with these contents:
w00t! Thanks to the scala interpretor, you didn't even need to recompile.
89
+
It's just as easy--just use the `-i` flag to point to either a server or file.
131
90
132
91
### Modifying the client library format
133
-
Don't like the default swagger client syntax? Want a different language supported? No problem! Swagger codegen
134
-
processes mustache templates with the [scalate](http://scalate.fusesource.org/) engine. You can modify our templates or
135
-
make your own.
92
+
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.
136
93
137
-
You can look at `src/main/resources/${your-language}` for examples. To make your own templates, create your own files
138
-
and override the `templateDir` in your script to point to the right place. It actually is that easy.
94
+
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.
139
95
140
96
### Where is Javascript???
141
97
See our [javascript library](http://github.com/swagger-api/swagger-js)--it's completely dynamic and doesn't require
@@ -148,102 +104,132 @@ If you don't want to call your server, you can save the swagger spec files into
Which simple passes `-DfileMap=src/test/resources/petstore` as an argument. Great for creating libraries on your
160
-
ci server... or while coding on an airplane.
110
+
Great for creating libraries on your ci server, from the [Swagger Editor](http://editor.swagger.io)... or while coding on an airplane.
161
111
162
-
### Validating your swagger spec
163
-
You can use the validation tool to see that your server is creating a proper spec file. If you want to learn
164
-
more about the spec file and format, please see [swagger-spec](https://github.com/swagger-api/swagger-spec). This
165
-
tool will read the server and generate a report of any violations of the spec. If there are violations, the
166
-
client codegen and ui may not work correctly.
112
+
### Customizing the generator
167
113
168
-
To validate an api and write output to ./swagger-errors.html:
114
+
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 modules/swagger-codegen/src/main/java/com/wordnik/swagger/codegen/languages/
118
+
AndroidClientCodegen.java
119
+
JavaClientCodegen.java
120
+
JaxRSServerCodegen.java
121
+
NodeJSServerCodegen.java
122
+
ObjcClientCodegen.java
123
+
PhpClientCodegen.java
124
+
PythonClientCodegen.java
125
+
ScalaClientCodegen.java
126
+
ScalatraServerCodegen.java
127
+
StaticDocCodegen.java
128
+
StaticHtmlGenerator.java
129
+
SwaggerGenerator.java
130
+
TizenClientCodegen.java
172
131
```
173
132
174
-
### Generating static api documentation
175
-
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.
133
+
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.
134
+
135
+
To change, for example, the prefix for the Objective-C generated files, simply subclass the ObjcClientCodegen.java:
176
136
177
137
```
178
-
./bin/static-docs.sh
138
+
package com.mycompany.swagger.codegen;
139
+
140
+
import com.wordnik.swagger.codegen.languages.*;
141
+
142
+
public class MyObjcCodegen extends ObjcClientCodegen {
143
+
static {
144
+
PREFIX = "HELO";
145
+
}
146
+
}
179
147
```
180
148
181
-
Will produce the output here:
149
+
and specify the `classname` when running the generator:
Your subclass will now be loaded and overrides the `PREFIX` value in the superclass.
156
+
157
+
### Validating your swagger spec
158
+
159
+
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:
You can also use the codegen to generate a server for a couple different frameworks. Take a look here:
178
+
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:
200
179
201
-
*[javascript node.js Server generator](https://github.com/swagger-api/swagger-codegen/tree/master/samples/server-generator/node)
If you've spent time hand-crafting your swagger spec files, you can use the [SpecConverter](https://github.com/swagger-api/swagger-codegen/blob/master/src/main/scala/com/wordnik/swagger/codegen/SpecConverter.scala) to do the dirty work. For example:
This will create the swagger-codegen library from source.
235
222
236
223
```
237
-
./sbt assembly
224
+
mvn package
238
225
```
239
226
240
-
Note! The templates are included in the library generated. If you want to modify the templates, you'll need to
241
-
either repackage the library OR modify your codegen script to use a file path!
227
+
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
242
228
243
229
License
244
230
-------
245
231
246
-
Copyright 2014 Reverb Technologies, Inc.
232
+
Copyright 2015 Reverb Technologies, Inc.
247
233
248
234
Licensed under the Apache License, Version 2.0 (the "License");
249
235
you may not use this file except in compliance with the License.
0 commit comments