Skip to content

Commit 2b7a8ab

Browse files
frankkilcomminsfrankkilcommins
committed
chore(repo): simplify ReadMe and docs for 3.X
1 parent 60322d6 commit 2b7a8ab

12 files changed

+878
-770
lines changed

‎README.md‎

Lines changed: 121 additions & 770 deletions
Large diffs are not rendered by default.

‎docs/Swagger-Codegen-Logo.png‎

25.8 KB
Loading

‎docs/building.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Building
2+
3+
After cloning the project, you can build it from source with this command:
4+
5+
```sh
6+
mvn clean package
7+
```
8+
9+
## Homebrew
10+
11+
To install, run `brew install swagger-codegen`
12+
13+
Here is an example usage:
14+
15+
```sh
16+
swagger-codegen generate -i http://petstore.swagger.io/v2/swagger.json -l ruby -o /tmp/test/
17+
```
18+
19+
## To build a server stub
20+
21+
Please refer to [wiki](https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO) for more information.
22+
23+
## To build the codegen library
24+
25+
This will create the Swagger Codegen library from source.
26+
27+
```sh
28+
mvn package
29+
```
30+
31+
> 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.

‎docs/compatibility.md‎

Lines changed: 120 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/docker.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Docker
2+
3+
## Development in docker
4+
5+
You can use `run-in-docker.sh` to do all development. This script maps your local repository to `/gen`
6+
in the docker container. It also maps `~/.m2/repository` to the appropriate container location.
7+
8+
To execute `mvn package`:
9+
10+
```sh
11+
git clone https://github.com/swagger-api/swagger-codegen
12+
cd swagger-codegen
13+
./run-in-docker.sh mvn package
14+
```
15+
16+
Build artifacts are now accessible in your working directory.
17+
18+
Once built, `run-in-docker.sh` will act as an executable for swagger-codegen-cli. To generate code, you'll need to output to a directory under `/gen` (e.g. `/gen/out`). For example:
19+
20+
```sh
21+
./run-in-docker.sh help # Executes 'help' command for swagger-codegen-cli
22+
./run-in-docker.sh langs # Executes 'langs' command for swagger-codegen-cli
23+
./run-in-docker.sh /gen/bin/go-petstore.sh # Builds the Go client
24+
./run-in-docker.sh generate -i modules/swagger-codegen/src/test/resources/2_0/petstore.yaml \
25+
-l go -o /gen/out/go-petstore -DpackageName=petstore # generates go client, outputs locally to ./out/go-petstore
26+
```
27+
28+
## Standalone generator Development in docker
29+
30+
See [standalone generator development](https://github.com/swagger-api/swagger-codegen/blob/3.0.0/standalone-gen-dev/standalone-generator-development.md)
31+
32+
## Run Docker in Vagrant
33+
34+
Prerequisite: install [Vagrant](https://www.vagrantup.com/downloads.html) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads).
35+
36+
```sh
37+
git clone http://github.com/swagger-api/swagger-codegen.git
38+
cd swagger-codegen
39+
vagrant up
40+
vagrant ssh
41+
cd /vagrant
42+
./run-in-docker.sh mvn package
43+
```
44+
45+
## Public Pre-built Docker images
46+
47+
- [Official web service](https://hub.docker.com/r/swaggerapi/swagger-generator-v3/)
48+
- [Official web service with "standard" user](https://hub.docker.com/r/swaggerapi/swagger-generator-v3-root/)
49+
- [official minimal web service](https://hub.docker.com/r/swaggerapi/swagger-generator-v3-minimal/)
50+
- [official CLI](https://hub.docker.com/r/swaggerapi/swagger-codegen-cli-v3/)
51+
52+
### Swagger Generator Docker Image
53+
54+
The Swagger Generator image provides a ready to use web application (swagger-generator) providing code generation services.
55+
56+
Image accepts the following env variables:
57+
58+
- `JAVA_MEM` e.g. `1024m`
59+
- `HTTP_PORT` e.g. `8080`
60+
- `HIDDEN_OPTIONS_PATH` (alternative to `HIDDEN_OPTIONS`): useful if attaching a volume containing a `hiddenOptions.yaml` file definining which languages to hide. e.g. `/data/hiddenOptions.yaml`
61+
- `HIDDEN_OPTIONS` (alternative to `HIDDEN_OPTIONS_PATH`): allows to pass hidden options as an env variable, in the format `{category}:{language},{language},{language}|{category}:{language},{language},{language}`
62+
e.g. `servers:foo,bar|clientsV3:wtf,isthis` where category can be `clients`, `servers`, `clientsV3`, `serversV3`
63+
64+
An example of running the container:
65+
66+
`docker pull swaggerapi/swagger-generator-v3`
67+
68+
`docker run -e "HIDDEN_OPTIONS=servers:foo,bar|clientsV3:fgf,sdsd" -e "JAVA_MEM=1024m" -e "HTTP_PORT=80" -p 80:80 --name swagger-generator-v3 -v /tmp:/jetty_home/lib/shared swaggerapi/swagger-generator-v3`
69+
70+
or
71+
72+
`docker run -e "HIDDEN_OPTIONS_PATH=/hiddenOptions.yaml" -e "JAVA_MEM=1024m" -e "HTTP_PORT=80" -p 80:80 --name swagger-generator-v3 -v /tmp:/jetty_home/lib/shared swaggerapi/swagger-generator-v3`
73+
74+
This docker image supports custom generators by dropping the generator jar into `/jetty_home/lib/shared` directory (typically via a docker volume); e.g having on host `/my/custom/coolgenerator.jar` and `/my/custom/weirdgenerator.jar` the following would have them added to generator service generators:
75+
76+
`docker run -e "HIDDEN_OPTIONS_PATH=/hiddenOptions.yaml" -e "JAVA_MEM=1024m" -e "HTTP_PORT=80" -p 80:80 --name swagger-generator-v3 -v /my/custom:/jetty_home/lib/shared swaggerapi/swagger-generator-v3`
77+
78+
Please note that up to version 3.0.20 you need to provide`-v /{WHATEVER_DIR}:/jetty_home/lib/shared` even if not using custom generators.
79+
80+
See also [online generators](./online-generators.md).
81+
82+
### Swagger Generator "Minimal" Docker Image
83+
84+
The Swagger Generator "Minimal" image can act as a self-hosted web application and API for generating code.
85+
86+
This container can be incorporated into a CI pipeline, and requires some docker orchestration to access generated code.
87+
88+
Example usage:
89+
90+
```sh
91+
# Start container and save the container id
92+
CID=$(docker run -d swaggerapi/swagger-generator-v3-minimal)
93+
# allow for startup
94+
sleep 5
95+
# Get the IP of the running container
96+
GEN_IP=$(docker inspect --format '{{.NetworkSettings.IPAddress}}' $CID)
97+
# Execute an HTTP request and store the download link
98+
curl -X POST \
99+
http://localhost:8080/api/generate \
100+
-H 'content-type: application/json' \
101+
-d '{
102+
"specURL" : "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml",
103+
"lang" : "jaxrs-jersey",
104+
"type" : "SERVER",
105+
"codegenVersion" : "V3"
106+
}' > result.zip
107+
# Shutdown the swagger generator image
108+
docker stop $CID && docker rm $CID
109+
```
110+
111+
In the example above, `result.zip` will contain the generated client.
112+
113+
See also [online generators](../README.md#online-generators).
114+
115+
### Swagger Codegen CLI Docker Image
116+
117+
The Swagger Codegen image acts as a standalone executable. It can be used as an alternative to installing via homebrew, or for developers who are unable to install Java or upgrade the installed version.
118+
119+
To generate code with this image, you'll need to mount a local location as a volume.
120+
121+
Example:
122+
123+
```sh
124+
docker run --rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli-v3 generate \
125+
-i http://petstore.swagger.io/v2/swagger.json \
126+
-l go \
127+
-o /local/out/go
128+
```
129+
130+
The generated code will be located under `./out/go` in the current directory.

‎docs/generation-selective.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Selective Generation
2+
3+
You may not want to generate *all* models in your project. Likewise you may want just one or two apis to be written. If that's the case, you can use system properties to control the output:
4+
5+
The default is generate *everything* supported by the specific library. Once you enable a feature, it will restrict the contents generated:
6+
7+
```sh
8+
# generate only models
9+
java -Dmodels {opts}
10+
11+
# generate only apis
12+
java -Dapis {opts}
13+
14+
# generate only supporting files
15+
java -DsupportingFiles
16+
17+
# generate models and supporting files
18+
java -Dmodels -DsupportingFiles
19+
```
20+
21+
To control the specific files being generated, you can pass a CSV list of what you want:
22+
23+
```sh
24+
# generate the User and Pet models only
25+
-Dmodels=User,Pet
26+
27+
# generate the User model and the supportingFile `StringUtil.java`:
28+
-Dmodels=User -DsupportingFiles=StringUtil.java
29+
```
30+
31+
To control generation of docs and tests for api and models, pass false to the option. For api, these options are `-DapiTests=false` and `-DapiDocs=false`. For models, `-DmodelTests=false` and `-DmodelDocs=false`.
32+
These options default to true and don't limit the generation of the feature options listed above (like `-Dapi`):
33+
34+
```sh
35+
# generate only models (with tests and documentation)
36+
java -Dmodels {opts}
37+
38+
# generate only models (with tests but no documentation)
39+
java -Dmodels -DmodelDocs=false {opts}
40+
41+
# generate only User and Pet models (no tests and no documentation)
42+
java -Dmodels=User,Pet -DmodelTests=false {opts}
43+
44+
# generate only apis (without tests)
45+
java -Dapis -DapiTests=false {opts}
46+
47+
# generate only apis (modelTests option is ignored)
48+
java -Dapis -DmodelTests=false {opts}
49+
```
50+
51+
When using selective generation, _only_ the templates needed for the specific generation will be used.
52+
53+
## Ignore file format
54+
55+
Swagger Codegen supports a `.swagger-codegen-ignore` file, similar to `.gitignore` or `.dockerignore` you're probably already familiar with.
56+
57+
The ignore file allows for better control over overwriting existing files than the `--skip-overwrite` flag. With the ignore file, you can specify individual files or directories can be ignored. This can be useful, for example if you only want a subset of the generated code.
58+
59+
Examples:
60+
61+
```sh
62+
# Swagger Codegen Ignore
63+
# Lines beginning with a # are comments
64+
65+
# This should match build.sh located anywhere.
66+
build.sh
67+
68+
# Matches build.sh in the root
69+
/build.sh
70+
71+
# Exclude all recursively
72+
docs/**
73+
74+
# Explicitly allow files excluded by other rules
75+
!docs/UserApi.md
76+
77+
# Recursively exclude directories named Api
78+
# You can't negate files below this directory.
79+
src/**/Api/
80+
81+
# When this file is nested under /Api (excluded above),
82+
# this rule is ignored because parent directory is excluded by previous rule.
83+
!src/**/PetApiTests.cs
84+
85+
# Exclude a single, nested file explicitly
86+
src/IO.Swagger.Test/Model/AnimalFarmTests.cs
87+
```
88+
89+
The `.swagger-codegen-ignore` file must exist in the root of the output directory.
90+
91+
Upon first code generation, you may also pass the CLI option `--ignore-file-override=/path/to/ignore_file` for greater control over generated outputs. Note that this is a complete override, and will override the `.swagger-codegen-ignore` file in an output directory when regenerating code.
92+
93+
Editor support for `.swagger-codegen-ignore` files is available in IntelliJ via the [.ignore plugin](https://plugins.jetbrains.com/plugin/7495--ignore).

‎docs/generators-configuration.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Advanced Generator Configuration
2+
3+
There are different aspects of customizing the code generator (located in this version at [swagger codegen generator repo](https://github.com/swagger-api/swagger-codegen-generators)) beyond just creating or modifying templates. Each language has a supporting configuration file to handle different type mappings, etc:
4+
5+
```sh
6+
s -1 modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/
7+
8+
AbstractJavaCodegen.java
9+
AbstractJavaJAXRSServerCodegen.java
10+
... (results omitted)
11+
JavaClientCodegen.java
12+
JavaJAXRSSpecServerCodegen.java
13+
```
14+
15+
Each of these files creates reasonable defaults so you can get running quickly. If you want to configure package names, prefixes, model folders, etc. you can use a JSON config file to pass the values.
16+
17+
```sh
18+
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
19+
-i http://petstore.swagger.io/v2/swagger.json \
20+
-l java \
21+
-o samples/client/petstore/java \
22+
-c path/to/config.json
23+
```
24+
25+
and `config.json` contains the following as an example:
26+
27+
```json
28+
{
29+
"apiPackage" : "petstore"
30+
}
31+
```
32+
33+
Supported config options can be different per language. Running `config-help -l {lang}` will show available options.
34+
**These options are applied via configuration file (e.g. config.json) or by passing them with `-D{optionName}={optionValue}`**. (If `-D{optionName}` does not work, please open a [ticket](https://github.com/swagger-api/swagger-codegen/issues/new) and we'll look into it)
35+
36+
```sh
37+
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l java
38+
```
39+
40+
Output:
41+
42+
```text
43+
CONFIG OPTIONS
44+
modelPackage
45+
package for generated models
46+
47+
apiPackage
48+
package for generated api classes
49+
...... (results omitted)
50+
library
51+
library template (sub-template) to use:
52+
jersey1 - HTTP client: Jersey client 1.18. JSON processing: Jackson 2.4.2
53+
jersey2 - HTTP client: Jersey client 2.6
54+
feign - HTTP client: Netflix Feign 8.1.1. JSON processing: Jackson 2.6.3
55+
okhttp-gson (default) - HTTP client: OkHttp 2.4.0. JSON processing: Gson 2.3.1
56+
retrofit - HTTP client: OkHttp 2.4.0. JSON processing: Gson 2.3.1 (Retrofit 1.9.0)
57+
retrofit2 - HTTP client: OkHttp 2.5.0. JSON processing: Gson 2.4 (Retrofit 2.0.0-beta2)
58+
google-api-client - HTTP client: google-api-client 1.23.0. JSON processing: Jackson 2.8.9
59+
```
60+
61+
Your config file for Java can look like
62+
63+
```json
64+
{
65+
"groupId":"com.my.company",
66+
"artifactId":"MyClient",
67+
"artifactVersion":"1.2.0",
68+
"library":"feign"
69+
}
70+
```
71+
72+
For all the unspecified options default values will be used.
73+
74+
Another way to override default options is to extend the config class for the specific language.
75+
To change, for example, the prefix for the Objective-C generated files, simply subclass the ObjcClientCodegen.java:
76+
77+
```java
78+
package com.mycompany.swagger.codegen;
79+
80+
import io.swagger.codegen.languages.*;
81+
82+
public class MyObjcCodegen extends ObjcClientCodegen {
83+
static {
84+
PREFIX = "HELO";
85+
}
86+
}
87+
```
88+
89+
and specify the `classname` when running the generator:
90+
91+
```sh
92+
-l com.mycompany.swagger.codegen.MyObjcCodegen
93+
```
94+
95+
Your subclass will now be loaded and overrides the `PREFIX` value in the superclass.
96+
97+
## Bringing your own models
98+
99+
Sometimes you don't want a model generated. In this case, you can simply specify an import mapping to tell
100+
the codegen what _not_ to create. When doing this, every location that references a specific model will
101+
refer back to your classes.
102+
103+
> Note, this may not apply to all languages!
104+
105+
To specify an import mapping, use the `--import-mappings` argument and specify the model-to-import logic as such:
106+
107+
```sh
108+
--import-mappings Pet=my.models.MyPet
109+
```
110+
111+
Or for multiple mappings:
112+
113+
```sh
114+
--import-mappings Pet=my.models.MyPet,Order=my.models.MyOrder
115+
```
116+
117+
or
118+
119+
```sh
120+
--import-mappings Pet=my.models.MyPet --import-mappings Order=my.models.MyOrder
121+
```

0 commit comments

Comments
 (0)