Skip to content

Commit 77ab9e2

Browse files
frantumafrantuma
authored
Merge pull request #10239 from swagger-api/standalone-gen-dev-v2
docs: standalone generator development
2 parents f871209 + 740395e commit 77ab9e2

File tree

7 files changed

+121
-1
lines changed

7 files changed

+121
-1
lines changed

‎README.md

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -204,7 +204,7 @@ To build from source, you need the following installed and available in your `$P
204204
* [Apache maven 3.3.3 or greater](http://maven.apache.org/)
205205

206206
#### OS X Users
207-
Don't forget to install Java 8+.
207+
Don't forget to install Java 8+.
208208

209209
Export `JAVA_HOME` in order to use the supported Java version:
210210
```sh
@@ -259,6 +259,9 @@ Once built, `run-in-docker.sh` will act as an executable for swagger-codegen-cli
259259
./run-in-docker.sh generate -i modules/swagger-codegen/src/test/resources/2_0/petstore.yaml \
260260
-l go -o /gen/out/go-petstore -DpackageName=petstore # generates go client, outputs locally to ./out/go-petstore
261261
```
262+
#### Standalone generator Development in docker
263+
264+
See [standalone generator development](https://github.com/swagger-api/swagger-codegen/blob/master/standalone-gen-dev/standalone-generator-development.md)
262265

263266
#### Run Docker in Vagrant
264267
Prerequisite: install [Vagrant](https://www.vagrantup.com/downloads.html) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads).
@@ -458,6 +461,8 @@ java -cp output/myLibrary/target/myClientCodegen-swagger-codegen-1.0.0.jar:modul
458461
-o myClient
459462
```
460463

464+
See also [standalone generator development](https://github.com/swagger-api/swagger-codegen/blob/master/standalone-gen-dev/standalone-generator-development.md)
465+
461466
### Where is Javascript???
462467
See our [javascript library](http://github.com/swagger-api/swagger-js)--it's completely dynamic and doesn't require
463468
static code generation.

‎modules/swagger-codegen/src/main/resources/codegen/myFile.template

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
2+
# This is a sample supporting file mustache template.

‎standalone-gen-dev/docker-entrypoint.sh

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#!/usr/bin/env bash
2+
3+
set -euo pipefail
4+
5+
# GEN_DIR allows to share the entrypoint between Dockerfile and run-in-docker.sh (backward compatible)
6+
GEN_DIR=${GEN_DIR:-/opt/swagger-codegen}
7+
JAVA_OPTS=${JAVA_OPTS:-"-Xmx1024M -Dlogback.configurationFile=conf/logback.xml"}
8+
9+
cli="${GEN_DIR}"
10+
codegen2="${cli}/swagger-codegen-cli.jar"
11+
12+
(cd "${GEN_DIR}" && exec mvn -Duser.home=$(dirname MAVEN_CONFIG) package)
13+
command=$1
14+
shift
15+
exec java ${JAVA_OPTS} -cp "${codegen2}:${GEN_DIR}/target/*" "io.swagger.codegen.SwaggerCodegen" "${command}" "$@"
16+

‎standalone-gen-dev/docker-stub.sh

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
#!/bin/sh
2+
set -euo pipefail
3+
# GEN_DIR allows to share the entrypoint between Dockerfile and run-in-docker.sh (backward compatible)
4+
GEN_DIR=${GEN_DIR:-/opt/swagger-codegen}
5+
JAVA_OPTS=${JAVA_OPTS:-"-Xmx1024M -Dlogback.configurationFile=conf/logback.xml"}
6+
7+
codegen2="${GEN_DIR}/swagger-codegen-cli.jar"
8+
9+
command=$1
10+
exec java ${JAVA_OPTS} -jar "${codegen2}" "meta" "$@"

‎standalone-gen-dev/generator-stub-docker.sh

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
#!/bin/bash
2+
set -exo pipefail
3+
4+
cd "$(dirname ${BASH_SOURCE})"
5+
6+
docker run --rm -it \
7+
-w /gen \
8+
-e GEN_DIR=/gen \
9+
-v "${PWD}:/gen" \
10+
--entrypoint /gen/docker-stub.sh \
11+
openjdk:8-jre-alpine "$@"

‎standalone-gen-dev/run-in-docker.sh

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
#!/bin/bash
2+
set -exo pipefail
3+
4+
cd "$(dirname ${BASH_SOURCE})"
5+
6+
maven_cache_repo="${HOME}/.m2/repository"
7+
8+
mkdir -p "${maven_cache_repo}"
9+
10+
docker run --rm -it \
11+
-w /gen \
12+
-e GEN_DIR=/gen \
13+
-e MAVEN_CONFIG=/var/maven/.m2 \
14+
-u "$(id -u):$(id -g)" \
15+
-v "${PWD}:/gen" \
16+
-v "${maven_cache_repo}:/var/maven/.m2/repository" \
17+
--entrypoint /gen/docker-entrypoint.sh \
18+
maven:3-jdk-8 "$@"

‎standalone-gen-dev/standalone-generator-development.md

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
### Swagger Codegen 2.x Standalone generator development (separate project/repo)
2+
3+
As described in [Readme](https://github.com/swagger-api/swagger-codegen/tree/master#making-your-own-codegen-modules),
4+
a new generator can be implemented by starting with a project stub generated by the `meta` command of `swagger-codegen-cli`.
5+
6+
This can be achieved without needing to clone the `swagger-codegen` repo, by downloading and running the jar, e.g.:
7+
8+
```
9+
wget https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.13/swagger-codegen-cli-2.4.13.jar -O swagger-codegen-cli.jar
10+
java -jar swagger-codegen-cli.jar meta -o output/myLibrary -n myClientCodegen -p com.my.company.codegen
11+
```
12+
13+
Such generator can be then made available to the CLI by adding it to the classpath, allowing to run/test it via the command line CLI,
14+
add it to the build pipeline and so on, as mentioned in [Readme](https://github.com/swagger-api/swagger-codegen/tree/master#making-your-own-codegen-modules).
15+
16+
17+
#### Development in docker
18+
19+
Similar to what mentioned in Readme [development in docker section](https://github.com/swagger-api/swagger-codegen/tree/master#development-in-docker), a standalone generator can be built and run in docker, without need of a java/maven environment on the local machine.
20+
21+
Generate the initial project:
22+
23+
```bash
24+
25+
# project dir
26+
TARGET_DIR=/tmp/codegen/mygenerator
27+
mkdir -p $TARGET_DIR
28+
cd $TARGET_DIR
29+
# generated code location
30+
GENERATED_CODE_DIR=generated
31+
mkdir -p $GENERATED_CODE_DIR
32+
# download desired version
33+
wget https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.13/swagger-codegen-cli-2.4.13.jar -O swagger-codegen-cli.jar
34+
wget https://raw.githubusercontent.com/swagger-api/swagger-codegen/master/standalone-gen-dev/docker-stub.sh -O docker-stub.sh
35+
wget https://raw.githubusercontent.com/swagger-api/swagger-codegen/master/standalone-gen-dev/generator-stub-docker.sh -O generator-stub-docker.sh
36+
chmod +x *.sh
37+
# generated initial stub: -p <root package> -n <generator name>
38+
./generator-stub-docker.sh -p io.swagger.codegen.custom -n custom
39+
40+
```
41+
42+
A test definition if we don't have one:
43+
44+
```bash
45+
wget https://raw.githubusercontent.com/swagger-api/swagger-codegen/master/modules/swagger-codegen/src/test/resources/2_0/petstore.yaml -O petstore.yaml
46+
```
47+
48+
49+
Build the generator and run it against a definition (first time will be slower as it needs to download deps)
50+
51+
```bash
52+
wget https://raw.githubusercontent.com/swagger-api/swagger-codegen/master/standalone-gen-dev/run-in-docker.sh -O run-in-docker.sh
53+
wget https://raw.githubusercontent.com/swagger-api/swagger-codegen/master/standalone-gen-dev/docker-entrypoint.sh -O docker-entrypoint.sh
54+
chmod +x *.sh
55+
./run-in-docker.sh generate -i petstore.yaml -l custom -o /gen/$GENERATED_CODE_DIR
56+
```
57+
58+

0 commit comments

Comments
 (0)