Skip to content

[Perl] Add auto-generated Perl documentation in Markdown #2320

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Mar 8, 2016
Merged

[Perl] Add auto-generated Perl documentation in Markdown #2320

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7d642b2
add doc for api method
wing328 Feb 11, 2016
e5ed295
add example to codegen parameter
wing328 Mar 5, 2016
855f46f
add api and model documentation
wing328 Mar 6, 2016
1b652da
fix MD in perl doc
wing328 Mar 6, 2016
4ec8003
add isPrimitiveType,baseType to parameter
wing328 Mar 6, 2016
9eecccb
fix java docstring
wing328 Mar 6, 2016
9c7316d
fix return type in perl doc
wing328 Mar 8, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions modules/swagger-codegen/src/main/java/io/swagger/codegen/AbstractGenerator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@ public Reader getTemplateReader(String name) {
*
* @param config Codegen config
* @param templateFile Template file
* @return String Full template file path
*/
public String getFullTemplateFile(CodegenConfig config, String templateFile) {
String library = config.getLibrary();
Expand Down
14 changes: 14 additions & 0 deletions modules/swagger-codegen/src/main/java/io/swagger/codegen/CodegenConfig.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ public interface CodegenConfig {

String apiTestFileFolder();

String apiDocFileFolder();

String fileSuffix();

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

String modelTestFileFolder();

String modelDocFileFolder();

String modelPackage();

String toApiName(String name);
Expand Down Expand Up @@ -99,6 +103,10 @@ public interface CodegenConfig {

Map<String, String> modelTestTemplateFiles();

Map<String, String> apiDocTemplateFiles();

Map<String, String> modelDocTemplateFiles();

Set<String> languageSpecificPrimitives();

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

String toModelTestFilename(String name);

String toApiDocFilename(String name);

String toModelDocFilename(String name);

String toModelImport(String name);

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

String apiTestFilename(String templateName, String tag);

String apiDocFilename(String templateName, String tag);

boolean shouldOverwrite(String filename);

boolean isSkipOverwrite();
Expand Down
4 changes: 3 additions & 1 deletion modules/swagger-codegen/src/main/java/io/swagger/codegen/CodegenParameter.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,9 @@
public class CodegenParameter {
public Boolean isFormParam, isQueryParam, isPathParam, isHeaderParam,
isCookieParam, isBodyParam, hasMore, isContainer,
secondaryParam, isCollectionFormatMulti;
secondaryParam, isCollectionFormatMulti, isPrimitiveType;
public String baseName, paramName, dataType, datatypeWithEnum, collectionFormat, description, baseType, defaultValue;
public String example; // example value (x-example)
public String jsonSchema;
public Boolean isString, isInteger, isLong, isFloat, isDouble, isByteArray, isBinary, isBoolean, isDate, isDateTime;
public Boolean isListContainer, isMapContainer;
Expand Down Expand Up @@ -107,6 +108,7 @@ public CodegenParameter copy() {
output.multipleOf = this.multipleOf;
output.jsonSchema = this.jsonSchema;
output.defaultValue = this.defaultValue;
output.example = this.example;
output.isEnum = this.isEnum;
if (this._enum != null) {
output._enum = new ArrayList<String>(this._enum);
Expand Down
119 changes: 118 additions & 1 deletion modules/swagger-codegen/src/main/java/io/swagger/codegen/DefaultCodegen.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,8 @@ public class DefaultCodegen {
protected Map<String, String> modelTemplateFiles = new HashMap<String, String>();
protected Map<String, String> apiTestTemplateFiles = new HashMap<String, String>();
protected Map<String, String> modelTestTemplateFiles = new HashMap<String, String>();
protected Map<String, String> apiDocTemplateFiles = new HashMap<String, String>();
protected Map<String, String> modelDocTemplateFiles = new HashMap<String, String>();
protected String templateDir;
protected String embeddedTemplateDir;
protected Map<String, Object> additionalProperties = new HashMap<String, Object>();
Expand Down Expand Up @@ -228,6 +230,14 @@ public String embeddedTemplateDir() {
}
}

public Map<String, String> apiDocTemplateFiles() {
return apiDocTemplateFiles;
}

public Map<String, String> modelDocTemplateFiles() {
return modelDocTemplateFiles;
}

public Map<String, String> apiTestTemplateFiles() {
return apiTestTemplateFiles;
}
Expand Down Expand Up @@ -260,6 +270,14 @@ public String modelTestFileFolder() {
return outputFolder + "/" + testPackage().replace('.', '/');
}

public String apiDocFileFolder() {
return outputFolder;
}

public String modelDocFileFolder() {
return outputFolder;
}

public Map<String, Object> additionalProperties() {
return additionalProperties;
}
Expand Down Expand Up @@ -322,6 +340,16 @@ public String toApiFilename(String name) {
return toApiName(name);
}

/**
* Return the file name of the Api Documentation
*
* @param name the file name of the Api
* @return the file name of the Api
*/
public String toApiDocFilename(String name) {
return toApiName(name);
}

/**
* Return the file name of the Api Test
*
Expand Down Expand Up @@ -362,6 +390,16 @@ public String toModelTestFilename(String name) {
return initialCaps(name) + "Test";
}

/**
* Return the capitalized file name of the model documentation
*
* @param name the model name
* @return the file name of the model
*/
public String toModelDocFilename(String name) {
return initialCaps(name);
}

/**
* Return the operation ID (method name)
*
Expand Down Expand Up @@ -614,13 +652,21 @@ public String toInstantiationType(Property p) {
}
}

/**
* Return the example value of the parameter.
*
* @param p Swagger property object
*/
public void setParameterExampleValue(CodegenParameter p) {

}

/**
* Return the example value of the property
*
* @param p Swagger property object
* @return string presentation of the example value of the property
*/
@SuppressWarnings("static-method")
public String toExampleValue(Property p) {
if(p.getExample() != null) {
return p.getExample().toString();
Expand Down Expand Up @@ -1452,6 +1498,14 @@ public CodegenOperation fromOperation(String path, String httpMethod, Operation
}
}
}

// set isPrimitiveType and baseType for allParams
/*if (languageSpecificPrimitives.contains(p.baseType)) {
p.isPrimitiveType = true;
p.baseType = getSwaggerType(p);
}*/


allParams.add(p);
if (param instanceof QueryParameter) {
p.isQueryParam = new Boolean(true);
Expand Down Expand Up @@ -1723,7 +1777,9 @@ public CodegenParameter fromParameter(Parameter param, Set<String> imports) {
prop.setRequired(bp.getRequired());
CodegenProperty cp = fromProperty("property", prop);
if (cp != null) {
p.baseType = cp.baseType;
p.dataType = cp.datatype;
p.isPrimitiveType = cp.isPrimitiveType;
p.isBinary = cp.datatype.toLowerCase().startsWith("byte");
}

Expand All @@ -1743,6 +1799,8 @@ public CodegenParameter fromParameter(Parameter param, Set<String> imports) {
}
imports.add(cp.baseType);
p.dataType = cp.datatype;
p.baseType = cp.complexType;
p.isPrimitiveType = cp.isPrimitiveType;
p.isContainer = true;
p.isListContainer = true;

Expand All @@ -1763,11 +1821,47 @@ public CodegenParameter fromParameter(Parameter param, Set<String> imports) {
name = getTypeDeclaration(name);
}
p.dataType = name;
p.baseType = name;
}
}
p.paramName = toParamName(bp.getName());
}

// set the example value
// if not specified in x-example, generate a default value
if (p.vendorExtensions.containsKey("x-example")) {
p.example = (String) p.vendorExtensions.get("x-example");
} else if (Boolean.TRUE.equals(p.isString)) {
p.example = p.paramName + "_example";
} else if (Boolean.TRUE.equals(p.isBoolean)) {
p.example = new String("true");
} else if (Boolean.TRUE.equals(p.isLong)) {
p.example = new String("789");
} else if (Boolean.TRUE.equals(p.isInteger)) {
p.example = new String("56");
} else if (Boolean.TRUE.equals(p.isFloat)) {
p.example = new String("3.4");
} else if (Boolean.TRUE.equals(p.isDouble)) {
p.example = new String("1.2");
} else if (Boolean.TRUE.equals(p.isBinary)) {
p.example = new String("BINARY_DATA_HERE");
} else if (Boolean.TRUE.equals(p.isByteArray)) {
p.example = new String("B");
} else if (Boolean.TRUE.equals(p.isDate)) {
p.example = new String("2013-10-20");
} else if (Boolean.TRUE.equals(p.isDateTime)) {
p.example = new String("2013-10-20T19:20:30+01:00");
} else if (param instanceof FormParameter &&
("file".equalsIgnoreCase(((FormParameter) param).getType()) ||
"file".equals(p.baseType))) {
p.isFile = true;
p.example = new String("/path/to/file.txt");
}

// set the parameter excample value
// should be overridden by lang codegen
setParameterExampleValue(p);

postProcessParameter(p);
return p;
}
Expand Down Expand Up @@ -2196,6 +2290,19 @@ public String apiFilename(String templateName, String tag) {
return apiFileFolder() + '/' + toApiFilename(tag) + suffix;
}

/**
* Return the full path and API documentation file
*
* @param templateName template name
* @param tag tag
*
* @return the API documentation file name with full path
*/
public String apiDocFilename(String templateName, String tag) {
String suffix = apiDocTemplateFiles().get(templateName);
return apiDocFileFolder() + '/' + toApiDocFilename(tag) + suffix;
}

/**
* Return the full path and API test file
*
Expand Down Expand Up @@ -2361,24 +2468,34 @@ public void setParameterBooleanFlagWithCodegenProperty(CodegenParameter paramete

if (Boolean.TRUE.equals(property.isString)) {
parameter.isString = true;
parameter.isPrimitiveType = true;
} else if (Boolean.TRUE.equals(property.isBoolean)) {
parameter.isBoolean = true;
parameter.isPrimitiveType = true;
} else if (Boolean.TRUE.equals(property.isLong)) {
parameter.isLong = true;
parameter.isPrimitiveType = true;
} else if (Boolean.TRUE.equals(property.isInteger)) {
parameter.isInteger = true;
parameter.isPrimitiveType = true;
} else if (Boolean.TRUE.equals(property.isDouble)) {
parameter.isDouble = true;
parameter.isPrimitiveType = true;
} else if (Boolean.TRUE.equals(property.isFloat)) {
parameter.isFloat = true;
parameter.isPrimitiveType = true;
} else if (Boolean.TRUE.equals(property.isByteArray)) {
parameter.isByteArray = true;
parameter.isPrimitiveType = true;
} else if (Boolean.TRUE.equals(property.isBinary)) {
parameter.isByteArray = true;
parameter.isPrimitiveType = true;
} else if (Boolean.TRUE.equals(property.isDate)) {
parameter.isDate = true;
parameter.isPrimitiveType = true;
} else if (Boolean.TRUE.equals(property.isDateTime)) {
parameter.isDateTime = true;
parameter.isPrimitiveType = true;
} else {
LOGGER.debug("Property type is not primitive: " + property.datatype);
}
Expand Down
45 changes: 45 additions & 0 deletions modules/swagger-codegen/src/main/java/io/swagger/codegen/DefaultGenerator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,6 +263,28 @@ public Reader getTemplate(String name) {
writeToFile(filename, tmpl.execute(models));
files.add(new File(filename));
}

// to generate model documentation files
for (String templateName : config.modelDocTemplateFiles().keySet()) {
String suffix = config.modelDocTemplateFiles().get(templateName);
String filename = config.modelDocFileFolder() + File.separator + config.toModelDocFilename(name) + suffix;
if (!config.shouldOverwrite(filename)) {
continue;
}
String templateFile = getFullTemplateFile(config, templateName);
String template = readTemplate(templateFile);
Template tmpl = Mustache.compiler()
.withLoader(new Mustache.TemplateLoader() {
@Override
public Reader getTemplate(String name) {
return getTemplateReader(getFullTemplateFile(config, name + ".mustache"));
}
})
.defaultValue("")
.compile(template);
writeToFile(filename, tmpl.execute(models));
files.add(new File(filename));
}
} catch (Exception e) {
throw new RuntimeException("Could not generate model '" + name + "'", e);
}
Expand Down Expand Up @@ -368,6 +390,29 @@ public Reader getTemplate(String name) {
files.add(new File(filename));
}

// to generate api documentation files
for (String templateName : config.apiDocTemplateFiles().keySet()) {
String filename = config.apiDocFilename(templateName, tag);
if (!config.shouldOverwrite(filename) && new File(filename).exists()) {
continue;
}

String templateFile = getFullTemplateFile(config, templateName);
String template = readTemplate(templateFile);
Template tmpl = Mustache.compiler()
.withLoader(new Mustache.TemplateLoader() {
@Override
public Reader getTemplate(String name) {
return getTemplateReader(getFullTemplateFile(config, name + ".mustache"));
}
})
.defaultValue("")
.compile(template);

writeToFile(filename, tmpl.execute(operation));
files.add(new File(filename));
}

} catch (Exception e) {
throw new RuntimeException("Could not generate api file for '" + tag + "'", e);
}
Expand Down
Loading