Skip to content

Commit e53a19f

Browse files
HugoMarioHugoMario
committed
Issue #179: added mustache templates for meta generator.
1 parent da11077 commit e53a19f

File tree

7 files changed

+390
-0
lines changed

7 files changed

+390
-0
lines changed

‎src/main/resources/mustache/codegen/README.mustache

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Swagger Codegen for the {{name}} library
2+
3+
## Overview
4+
This is a boiler-plate project to generate your own client library with Swagger. Its goal is
5+
to get you started with the basic plumbing so you can put in your own logic. It won't work without
6+
your changes applied.
7+
8+
## What's Swagger?
9+
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.
10+
11+
12+
Check out [OpenAPI-Spec](https://github.com/OAI/OpenAPI-Specification) for additional information about the Swagger project, including additional libraries with support for other languages and more.
13+
14+
## How do I use this?
15+
At this point, you've likely generated a client setup. It will include something along these lines:
16+
17+
```
18+
.
19+
|- README.md // this file
20+
|- pom.xml // build script
21+
|-- src
22+
|--- main
23+
|---- java
24+
|----- {{generatorPackage}}.{{generatorClass}}.java // generator file
25+
|---- resources
26+
|----- {{name}} // template files
27+
|----- META-INF
28+
|------ services
29+
|------- io.swagger.codegen.CodegenConfig
30+
```
31+
32+
You _will_ need to make changes in at least the following:
33+
34+
`{{generatorClass}}.java`
35+
36+
Templates in this folder:
37+
38+
`src/main/resources/{{name}}`
39+
40+
Once modified, you can run this:
41+
42+
```
43+
mvn package
44+
```
45+
46+
In your generator project. A single jar file will be produced in `target`. You can now use that with codegen:
47+
48+
```
49+
java -cp /path/to/swagger-codegen-cli.jar:/path/to/your.jar io.swagger.codegen.Codegen -l {{name}} -i /path/to/swagger.yaml -o ./test
50+
```
51+
52+
Now your templates are available to the client generator and you can write output values
53+
54+
## But how do I modify this?
55+
The `{{generatorClass}}.java` has comments in it--lots of comments. There is no good substitute
56+
for reading the code more, though. See how the `{{generatorClass}}` implements `CodegenConfig`.
57+
That class has the signature of all values that can be overridden.
58+
59+
For the templates themselves, you have a number of values available to you for generation.
60+
You can execute the `java` command from above while passing different debug flags to show
61+
the object you have available during client generation:
62+
63+
```
64+
# The following additional debug options are available for all codegen targets:
65+
# -DdebugSwagger prints the OpenAPI Specification as interpreted by the codegen
66+
# -DdebugModels prints models passed to the template engine
67+
# -DdebugOperations prints operations passed to the template engine
68+
# -DdebugSupportingFiles prints additional data passed to the template engine
69+
70+
java -DdebugOperations -cp /path/to/swagger-codegen-cli.jar:/path/to/your.jar io.swagger.codegen.Codegen -l {{name}} -i /path/to/swagger.yaml -o ./test
71+
```
72+
73+
Will, for example, output the debug info for operations. You can use this info
74+
in the `api.mustache` file.

‎src/main/resources/mustache/codegen/api.template

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
2+
# This is a sample api mustache template. It is representing a ficticous
3+
# language and won't be usable or compile to anything without lots of changes.
4+
# Use it as an example. You can access the variables in the generator object
5+
# like such:
6+
7+
# use the package from the `apiPackage` variable
8+
package: {{package}}
9+
10+
# operations block
11+
{{#operations}}
12+
classname: {{classname}}
13+
14+
# loop over each operation in the API:
15+
{{#operation}}
16+
17+
# each operation has an `operationId`:
18+
operationId: {{operationId}}
19+
20+
# and parameters:
21+
{{#allParams}}
22+
{{paramName}}: {{dataType}}
23+
{{/allParams}}
24+
25+
{{/operation}}
26+
27+
# end of operations block
28+
{{/operations}}

‎src/main/resources/mustache/codegen/generatorClass.mustache

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
package {{generatorPackage}};
2+
3+
import io.swagger.codegen.v3.*;
4+
import io.swagger.codegen.v3.generators.DefaultCodegenConfig;
5+
6+
import java.util.*;
7+
import java.io.File;
8+
9+
public class {{generatorClass}} extends DefaultCodegenConfig {
10+
11+
// source folder where to write the files
12+
protected String sourceFolder = "src";
13+
protected String apiVersion = "1.0.0";
14+
15+
/**
16+
* Configures the type of generator.
17+
*
18+
* @return the CodegenType for this generator
19+
* @see io.swagger.codegen.CodegenType
20+
*/
21+
public CodegenType getTag() {
22+
return CodegenType.CLIENT;
23+
}
24+
25+
/**
26+
* Configures a friendly name for the generator. This will be used by the generator
27+
* to select the library with the -l flag.
28+
*
29+
* @return the friendly name for the generator
30+
*/
31+
public String getName() {
32+
return "{{name}}";
33+
}
34+
35+
/**
36+
* Returns human-friendly help for the generator. Provide the consumer with help
37+
* tips, parameters here
38+
*
39+
* @return A string value for the help message
40+
*/
41+
public String getHelp() {
42+
return "Generates a {{name}} client library.";
43+
}
44+
45+
public {{generatorClass}}() {
46+
super();
47+
48+
// set the output folder here
49+
outputFolder = "generated-code/{{name}}";
50+
51+
/**
52+
* Models. You can write model files using the modelTemplateFiles map.
53+
* if you want to create one template for file, you can do so here.
54+
* for multiple files for model, just put another entry in the `modelTemplateFiles` with
55+
* a different extension
56+
*/
57+
modelTemplateFiles.put(
58+
"model.mustache", // the template to use
59+
".sample"); // the extension for each file to write
60+
61+
/**
62+
* Api classes. You can write classes for each Api file with the apiTemplateFiles map.
63+
* as with models, add multiple entries with different extensions for multiple files per
64+
* class
65+
*/
66+
apiTemplateFiles.put(
67+
"api.mustache", // the template to use
68+
".sample"); // the extension for each file to write
69+
70+
/**
71+
* Template Location. This is the location which templates will be read from. The generator
72+
* will use the resource stream to attempt to read the templates.
73+
*/
74+
templateDir = "{{name}}";
75+
76+
/**
77+
* Api Package. Optional, if needed, this can be used in templates
78+
*/
79+
apiPackage = "io.swagger.client.api";
80+
81+
/**
82+
* Model Package. Optional, if needed, this can be used in templates
83+
*/
84+
modelPackage = "io.swagger.client.model";
85+
86+
/**
87+
* Reserved words. Override this with reserved words specific to your language
88+
*/
89+
reservedWords = new HashSet<String> (
90+
Arrays.asList(
91+
"sample1", // replace with static values
92+
"sample2")
93+
);
94+
95+
/**
96+
* Additional Properties. These values can be passed to the templates and
97+
* are available in models, apis, and supporting files
98+
*/
99+
additionalProperties.put("apiVersion", apiVersion);
100+
101+
/**
102+
* Supporting Files. You can write single files for the generator with the
103+
* entire object tree available. If the input file has a suffix of `.mustache
104+
* it will be processed by the template engine. Otherwise, it will be copied
105+
*/
106+
supportingFiles.add(new SupportingFile("myFile.mustache", // the input template or file
107+
"", // the destination folder, relative `outputFolder`
108+
"myFile.sample") // the output file
109+
);
110+
111+
/**
112+
* Language Specific Primitives. These types will not trigger imports by
113+
* the client generator
114+
*/
115+
languageSpecificPrimitives = new HashSet<String>(
116+
Arrays.asList(
117+
"Type1", // replace these with your types
118+
"Type2")
119+
);
120+
}
121+
122+
/**
123+
* Escapes a reserved word as defined in the `reservedWords` array. Handle escaping
124+
* those terms here. This logic is only called if a variable matches the reserved words
125+
*
126+
* @return the escaped term
127+
*/
128+
@Override
129+
public String escapeReservedWord(String name) {
130+
return "_" + name; // add an underscore to the name
131+
}
132+
133+
/**
134+
* Location to write model files. You can use the modelPackage() as defined when the class is
135+
* instantiated
136+
*/
137+
public String modelFileFolder() {
138+
return outputFolder + "/" + sourceFolder + "/" + modelPackage().replace('.', File.separatorChar);
139+
}
140+
141+
/**
142+
* Location to write api files. You can use the apiPackage() as defined when the class is
143+
* instantiated
144+
*/
145+
@Override
146+
public String apiFileFolder() {
147+
return outputFolder + "/" + sourceFolder + "/" + apiPackage().replace('.', File.separatorChar);
148+
}
149+
150+
@Override
151+
public String getArgumentsLocation() {
152+
return null;
153+
}
154+
}

‎src/main/resources/mustache/codegen/model.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 model mustache template.

‎src/main/resources/mustache/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.

‎src/main/resources/mustache/codegen/pom.mustache

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
3+
<modelVersion>4.0.0</modelVersion>
4+
<groupId>io.swagger</groupId>
5+
<artifactId>{{name}}-swagger-codegen</artifactId>
6+
<packaging>jar</packaging>
7+
<name>{{name}}-swagger-codegen</name>
8+
<version>1.0.0</version>
9+
<build>
10+
<plugins>
11+
<plugin>
12+
<groupId>org.apache.maven.plugins</groupId>
13+
<artifactId>maven-enforcer-plugin</artifactId>
14+
<version>3.0.0-M1</version>
15+
<executions>
16+
<execution>
17+
<id>enforce-maven</id>
18+
<goals>
19+
<goal>enforce</goal>
20+
</goals>
21+
<configuration>
22+
<rules>
23+
<requireMavenVersion>
24+
<version>2.2.0</version>
25+
</requireMavenVersion>
26+
</rules>
27+
</configuration>
28+
</execution>
29+
</executions>
30+
</plugin>
31+
<plugin>
32+
<groupId>org.apache.maven.plugins</groupId>
33+
<artifactId>maven-surefire-plugin</artifactId>
34+
<version>2.12</version>
35+
<configuration>
36+
<systemProperties>
37+
<property>
38+
<name>loggerPath</name>
39+
<value>conf/log4j.properties</value>
40+
</property>
41+
</systemProperties>
42+
<argLine>-Xms512m -Xmx1500m</argLine>
43+
<parallel>methods</parallel>
44+
<forkMode>pertest</forkMode>
45+
</configuration>
46+
</plugin>
47+
48+
<!-- attach test jar -->
49+
<plugin>
50+
<groupId>org.apache.maven.plugins</groupId>
51+
<artifactId>maven-jar-plugin</artifactId>
52+
<version>2.2</version>
53+
<executions>
54+
<execution>
55+
<goals>
56+
<goal>jar</goal>
57+
<goal>test-jar</goal>
58+
</goals>
59+
</execution>
60+
</executions>
61+
<configuration>
62+
</configuration>
63+
</plugin>
64+
65+
<plugin>
66+
<groupId>org.codehaus.mojo</groupId>
67+
<artifactId>build-helper-maven-plugin</artifactId>
68+
<version>${build-helper-maven-plugin}</version>
69+
<executions>
70+
<execution>
71+
<id>add_sources</id>
72+
<phase>generate-sources</phase>
73+
<goals>
74+
<goal>add-source</goal>
75+
</goals>
76+
<configuration>
77+
<sources>
78+
<source>src/main/java</source>
79+
</sources>
80+
</configuration>
81+
</execution>
82+
<execution>
83+
<id>add_test_sources</id>
84+
<phase>generate-test-sources</phase>
85+
<goals>
86+
<goal>add-test-source</goal>
87+
</goals>
88+
<configuration>
89+
<sources>
90+
<source>src/test/java</source>
91+
</sources>
92+
</configuration>
93+
</execution>
94+
</executions>
95+
</plugin>
96+
<plugin>
97+
<groupId>org.apache.maven.plugins</groupId>
98+
<artifactId>maven-compiler-plugin</artifactId>
99+
<version>3.6.1</version>
100+
<configuration>
101+
<source>1.8</source>
102+
<target>1.8</target>
103+
</configuration>
104+
</plugin>
105+
</plugins>
106+
</build>
107+
<dependencies>
108+
<dependency>
109+
<groupId>io.swagger.codegen.v3</groupId>
110+
<artifactId>swagger-codegen</artifactId>
111+
<version>${swagger-codegen-version}</version>
112+
<scope>provided</scope>
113+
</dependency>
114+
<dependency>
115+
<groupId>io.swagger.codegen.v3</groupId>
116+
<artifactId>swagger-codegen-generators</artifactId>
117+
<version>${swagger-codegen-generators-version}</version>
118+
<scope>provided</scope>
119+
</dependency>
120+
</dependencies>
121+
<properties>
122+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
123+
<swagger-codegen-version>{{swaggerCodegenVersion}}</swagger-codegen-version>
124+
<swagger-codegen-generators-version>{{swaggerCodegenGeneratorsVersion}}</swagger-codegen-generators-version>
125+
<maven-plugin-version>1.0.0</maven-plugin-version>
126+
<junit-version>4.8.1</junit-version>
127+
<build-helper-maven-plugin>3.0.0</build-helper-maven-plugin>
128+
</properties>
129+
</project>

0 commit comments

Comments
 (0)