Skip to content

Commit 70cd71f

Browse files
wing328wing328
committed
Merge pull request #2320 from wing328/perl_doc
[Perl] Add auto-generated Perl documentation in Markdown
2 parents c943434 + 9c7316d commit 70cd71f

File tree

24 files changed

+1613
-13
lines changed

24 files changed

+1613
-13
lines changed

‎modules/swagger-codegen/src/main/java/io/swagger/codegen/AbstractGenerator.java

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ public Reader getTemplateReader(String name) {
6969
*
7070
* @param config Codegen config
7171
* @param templateFile Template file
72+
* @return String Full template file path
7273
*/
7374
public String getFullTemplateFile(CodegenConfig config, String templateFile) {
7475
String library = config.getLibrary();

‎modules/swagger-codegen/src/main/java/io/swagger/codegen/CodegenConfig.java

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,8 @@ public interface CodegenConfig {
2929

3030
String apiTestFileFolder();
3131

32+
String apiDocFileFolder();
33+
3234
String fileSuffix();
3335

3436
String outputFolder();
@@ -41,6 +43,8 @@ public interface CodegenConfig {
4143

4244
String modelTestFileFolder();
4345

46+
String modelDocFileFolder();
47+
4448
String modelPackage();
4549

4650
String toApiName(String name);
@@ -99,6 +103,10 @@ public interface CodegenConfig {
99103

100104
Map<String, String> modelTestTemplateFiles();
101105

106+
Map<String, String> apiDocTemplateFiles();
107+
108+
Map<String, String> modelDocTemplateFiles();
109+
102110
Set<String> languageSpecificPrimitives();
103111

104112
void preprocessSwagger(Swagger swagger);
@@ -115,6 +123,10 @@ public interface CodegenConfig {
115123

116124
String toModelTestFilename(String name);
117125

126+
String toApiDocFilename(String name);
127+
128+
String toModelDocFilename(String name);
129+
118130
String toModelImport(String name);
119131

120132
String toApiImport(String name);
@@ -137,6 +149,8 @@ public interface CodegenConfig {
137149

138150
String apiTestFilename(String templateName, String tag);
139151

152+
String apiDocFilename(String templateName, String tag);
153+
140154
boolean shouldOverwrite(String filename);
141155

142156
boolean isSkipOverwrite();

‎modules/swagger-codegen/src/main/java/io/swagger/codegen/CodegenParameter.java

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,9 @@
88
public class CodegenParameter {
99
public Boolean isFormParam, isQueryParam, isPathParam, isHeaderParam,
1010
isCookieParam, isBodyParam, hasMore, isContainer,
11-
secondaryParam, isCollectionFormatMulti;
11+
secondaryParam, isCollectionFormatMulti, isPrimitiveType;
1212
public String baseName, paramName, dataType, datatypeWithEnum, collectionFormat, description, baseType, defaultValue;
13+
public String example; // example value (x-example)
1314
public String jsonSchema;
1415
public Boolean isString, isInteger, isLong, isFloat, isDouble, isByteArray, isBinary, isBoolean, isDate, isDateTime;
1516
public Boolean isListContainer, isMapContainer;
@@ -107,6 +108,7 @@ public CodegenParameter copy() {
107108
output.multipleOf = this.multipleOf;
108109
output.jsonSchema = this.jsonSchema;
109110
output.defaultValue = this.defaultValue;
111+
output.example = this.example;
110112
output.isEnum = this.isEnum;
111113
if (this._enum != null) {
112114
output._enum = new ArrayList<String>(this._enum);

‎modules/swagger-codegen/src/main/java/io/swagger/codegen/DefaultCodegen.java

Lines changed: 118 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,8 @@ public class DefaultCodegen {
6969
protected Map<String, String> modelTemplateFiles = new HashMap<String, String>();
7070
protected Map<String, String> apiTestTemplateFiles = new HashMap<String, String>();
7171
protected Map<String, String> modelTestTemplateFiles = new HashMap<String, String>();
72+
protected Map<String, String> apiDocTemplateFiles = new HashMap<String, String>();
73+
protected Map<String, String> modelDocTemplateFiles = new HashMap<String, String>();
7274
protected String templateDir;
7375
protected String embeddedTemplateDir;
7476
protected Map<String, Object> additionalProperties = new HashMap<String, Object>();
@@ -228,6 +230,14 @@ public String embeddedTemplateDir() {
228230
}
229231
}
230232

233+
public Map<String, String> apiDocTemplateFiles() {
234+
return apiDocTemplateFiles;
235+
}
236+
237+
public Map<String, String> modelDocTemplateFiles() {
238+
return modelDocTemplateFiles;
239+
}
240+
231241
public Map<String, String> apiTestTemplateFiles() {
232242
return apiTestTemplateFiles;
233243
}
@@ -260,6 +270,14 @@ public String modelTestFileFolder() {
260270
return outputFolder + "/" + testPackage().replace('.', '/');
261271
}
262272

273+
public String apiDocFileFolder() {
274+
return outputFolder;
275+
}
276+
277+
public String modelDocFileFolder() {
278+
return outputFolder;
279+
}
280+
263281
public Map<String, Object> additionalProperties() {
264282
return additionalProperties;
265283
}
@@ -322,6 +340,16 @@ public String toApiFilename(String name) {
322340
return toApiName(name);
323341
}
324342

343+
/**
344+
* Return the file name of the Api Documentation
345+
*
346+
* @param name the file name of the Api
347+
* @return the file name of the Api
348+
*/
349+
public String toApiDocFilename(String name) {
350+
return toApiName(name);
351+
}
352+
325353
/**
326354
* Return the file name of the Api Test
327355
*
@@ -362,6 +390,16 @@ public String toModelTestFilename(String name) {
362390
return initialCaps(name) + "Test";
363391
}
364392

393+
/**
394+
* Return the capitalized file name of the model documentation
395+
*
396+
* @param name the model name
397+
* @return the file name of the model
398+
*/
399+
public String toModelDocFilename(String name) {
400+
return initialCaps(name);
401+
}
402+
365403
/**
366404
* Return the operation ID (method name)
367405
*
@@ -614,13 +652,21 @@ public String toInstantiationType(Property p) {
614652
}
615653
}
616654

655+
/**
656+
* Return the example value of the parameter.
657+
*
658+
* @param p Swagger property object
659+
*/
660+
public void setParameterExampleValue(CodegenParameter p) {
661+
662+
}
663+
617664
/**
618665
* Return the example value of the property
619666
*
620667
* @param p Swagger property object
621668
* @return string presentation of the example value of the property
622669
*/
623-
@SuppressWarnings("static-method")
624670
public String toExampleValue(Property p) {
625671
if(p.getExample() != null) {
626672
return p.getExample().toString();
@@ -1452,6 +1498,14 @@ public CodegenOperation fromOperation(String path, String httpMethod, Operation
14521498
}
14531499
}
14541500
}
1501+
1502+
// set isPrimitiveType and baseType for allParams
1503+
/*if (languageSpecificPrimitives.contains(p.baseType)) {
1504+
p.isPrimitiveType = true;
1505+
p.baseType = getSwaggerType(p);
1506+
}*/
1507+
1508+
14551509
allParams.add(p);
14561510
if (param instanceof QueryParameter) {
14571511
p.isQueryParam = new Boolean(true);
@@ -1723,7 +1777,9 @@ public CodegenParameter fromParameter(Parameter param, Set<String> imports) {
17231777
prop.setRequired(bp.getRequired());
17241778
CodegenProperty cp = fromProperty("property", prop);
17251779
if (cp != null) {
1780+
p.baseType = cp.baseType;
17261781
p.dataType = cp.datatype;
1782+
p.isPrimitiveType = cp.isPrimitiveType;
17271783
p.isBinary = cp.datatype.toLowerCase().startsWith("byte");
17281784
}
17291785

@@ -1743,6 +1799,8 @@ public CodegenParameter fromParameter(Parameter param, Set<String> imports) {
17431799
}
17441800
imports.add(cp.baseType);
17451801
p.dataType = cp.datatype;
1802+
p.baseType = cp.complexType;
1803+
p.isPrimitiveType = cp.isPrimitiveType;
17461804
p.isContainer = true;
17471805
p.isListContainer = true;
17481806

@@ -1763,11 +1821,47 @@ public CodegenParameter fromParameter(Parameter param, Set<String> imports) {
17631821
name = getTypeDeclaration(name);
17641822
}
17651823
p.dataType = name;
1824+
p.baseType = name;
17661825
}
17671826
}
17681827
p.paramName = toParamName(bp.getName());
17691828
}
17701829

1830+
// set the example value
1831+
// if not specified in x-example, generate a default value
1832+
if (p.vendorExtensions.containsKey("x-example")) {
1833+
p.example = (String) p.vendorExtensions.get("x-example");
1834+
} else if (Boolean.TRUE.equals(p.isString)) {
1835+
p.example = p.paramName + "_example";
1836+
} else if (Boolean.TRUE.equals(p.isBoolean)) {
1837+
p.example = new String("true");
1838+
} else if (Boolean.TRUE.equals(p.isLong)) {
1839+
p.example = new String("789");
1840+
} else if (Boolean.TRUE.equals(p.isInteger)) {
1841+
p.example = new String("56");
1842+
} else if (Boolean.TRUE.equals(p.isFloat)) {
1843+
p.example = new String("3.4");
1844+
} else if (Boolean.TRUE.equals(p.isDouble)) {
1845+
p.example = new String("1.2");
1846+
} else if (Boolean.TRUE.equals(p.isBinary)) {
1847+
p.example = new String("BINARY_DATA_HERE");
1848+
} else if (Boolean.TRUE.equals(p.isByteArray)) {
1849+
p.example = new String("B");
1850+
} else if (Boolean.TRUE.equals(p.isDate)) {
1851+
p.example = new String("2013-10-20");
1852+
} else if (Boolean.TRUE.equals(p.isDateTime)) {
1853+
p.example = new String("2013-10-20T19:20:30+01:00");
1854+
} else if (param instanceof FormParameter &&
1855+
("file".equalsIgnoreCase(((FormParameter) param).getType()) ||
1856+
"file".equals(p.baseType))) {
1857+
p.isFile = true;
1858+
p.example = new String("/path/to/file.txt");
1859+
}
1860+
1861+
// set the parameter excample value
1862+
// should be overridden by lang codegen
1863+
setParameterExampleValue(p);
1864+
17711865
postProcessParameter(p);
17721866
return p;
17731867
}
@@ -2196,6 +2290,19 @@ public String apiFilename(String templateName, String tag) {
21962290
return apiFileFolder() + '/' + toApiFilename(tag) + suffix;
21972291
}
21982292

2293+
/**
2294+
* Return the full path and API documentation file
2295+
*
2296+
* @param templateName template name
2297+
* @param tag tag
2298+
*
2299+
* @return the API documentation file name with full path
2300+
*/
2301+
public String apiDocFilename(String templateName, String tag) {
2302+
String suffix = apiDocTemplateFiles().get(templateName);
2303+
return apiDocFileFolder() + '/' + toApiDocFilename(tag) + suffix;
2304+
}
2305+
21992306
/**
22002307
* Return the full path and API test file
22012308
*
@@ -2361,24 +2468,34 @@ public void setParameterBooleanFlagWithCodegenProperty(CodegenParameter paramete
23612468

23622469
if (Boolean.TRUE.equals(property.isString)) {
23632470
parameter.isString = true;
2471+
parameter.isPrimitiveType = true;
23642472
} else if (Boolean.TRUE.equals(property.isBoolean)) {
23652473
parameter.isBoolean = true;
2474+
parameter.isPrimitiveType = true;
23662475
} else if (Boolean.TRUE.equals(property.isLong)) {
23672476
parameter.isLong = true;
2477+
parameter.isPrimitiveType = true;
23682478
} else if (Boolean.TRUE.equals(property.isInteger)) {
23692479
parameter.isInteger = true;
2480+
parameter.isPrimitiveType = true;
23702481
} else if (Boolean.TRUE.equals(property.isDouble)) {
23712482
parameter.isDouble = true;
2483+
parameter.isPrimitiveType = true;
23722484
} else if (Boolean.TRUE.equals(property.isFloat)) {
23732485
parameter.isFloat = true;
2486+
parameter.isPrimitiveType = true;
23742487
} else if (Boolean.TRUE.equals(property.isByteArray)) {
23752488
parameter.isByteArray = true;
2489+
parameter.isPrimitiveType = true;
23762490
} else if (Boolean.TRUE.equals(property.isBinary)) {
23772491
parameter.isByteArray = true;
2492+
parameter.isPrimitiveType = true;
23782493
} else if (Boolean.TRUE.equals(property.isDate)) {
23792494
parameter.isDate = true;
2495+
parameter.isPrimitiveType = true;
23802496
} else if (Boolean.TRUE.equals(property.isDateTime)) {
23812497
parameter.isDateTime = true;
2498+
parameter.isPrimitiveType = true;
23822499
} else {
23832500
LOGGER.debug("Property type is not primitive: " + property.datatype);
23842501
}

‎modules/swagger-codegen/src/main/java/io/swagger/codegen/DefaultGenerator.java

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -263,6 +263,28 @@ public Reader getTemplate(String name) {
263263
writeToFile(filename, tmpl.execute(models));
264264
files.add(new File(filename));
265265
}
266+
267+
// to generate model documentation files
268+
for (String templateName : config.modelDocTemplateFiles().keySet()) {
269+
String suffix = config.modelDocTemplateFiles().get(templateName);
270+
String filename = config.modelDocFileFolder() + File.separator + config.toModelDocFilename(name) + suffix;
271+
if (!config.shouldOverwrite(filename)) {
272+
continue;
273+
}
274+
String templateFile = getFullTemplateFile(config, templateName);
275+
String template = readTemplate(templateFile);
276+
Template tmpl = Mustache.compiler()
277+
.withLoader(new Mustache.TemplateLoader() {
278+
@Override
279+
public Reader getTemplate(String name) {
280+
return getTemplateReader(getFullTemplateFile(config, name + ".mustache"));
281+
}
282+
})
283+
.defaultValue("")
284+
.compile(template);
285+
writeToFile(filename, tmpl.execute(models));
286+
files.add(new File(filename));
287+
}
266288
} catch (Exception e) {
267289
throw new RuntimeException("Could not generate model '" + name + "'", e);
268290
}
@@ -368,6 +390,29 @@ public Reader getTemplate(String name) {
368390
files.add(new File(filename));
369391
}
370392

393+
// to generate api documentation files
394+
for (String templateName : config.apiDocTemplateFiles().keySet()) {
395+
String filename = config.apiDocFilename(templateName, tag);
396+
if (!config.shouldOverwrite(filename) && new File(filename).exists()) {
397+
continue;
398+
}
399+
400+
String templateFile = getFullTemplateFile(config, templateName);
401+
String template = readTemplate(templateFile);
402+
Template tmpl = Mustache.compiler()
403+
.withLoader(new Mustache.TemplateLoader() {
404+
@Override
405+
public Reader getTemplate(String name) {
406+
return getTemplateReader(getFullTemplateFile(config, name + ".mustache"));
407+
}
408+
})
409+
.defaultValue("")
410+
.compile(template);
411+
412+
writeToFile(filename, tmpl.execute(operation));
413+
files.add(new File(filename));
414+
}
415+
371416
} catch (Exception e) {
372417
throw new RuntimeException("Could not generate api file for '" + tag + "'", e);
373418
}

0 commit comments

Comments
 (0)