add doc for api method

This commit is contained in:
wing328 2016-02-11 18:43:51 +08:00
parent c9434347c2
commit 7d642b28b9
7 changed files with 143 additions and 4 deletions

View File

@ -29,6 +29,8 @@ public interface CodegenConfig {
String apiTestFileFolder();
String apiDocFileFolder();
String fileSuffix();
String outputFolder();
@ -41,6 +43,8 @@ public interface CodegenConfig {
String modelTestFileFolder();
String modelDocFileFolder();
String modelPackage();
String toApiName(String name);
@ -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);
@ -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);
@ -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();

View File

@ -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>();
@ -228,6 +230,14 @@ public class DefaultCodegen {
}
}
public Map<String, String> apiDocTemplateFiles() {
return apiDocTemplateFiles;
}
public Map<String, String> modelDocTemplateFiles() {
return modelDocTemplateFiles;
}
public Map<String, String> apiTestTemplateFiles() {
return apiTestTemplateFiles;
}
@ -260,6 +270,14 @@ public class DefaultCodegen {
return outputFolder + "/" + testPackage().replace('.', '/');
}
public String apiDocFileFolder() {
return outputFolder;
}
public String modelDocFileFolder() {
return outputFolder;
}
public Map<String, Object> additionalProperties() {
return additionalProperties;
}
@ -322,6 +340,16 @@ public class DefaultCodegen {
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
*
@ -362,6 +390,16 @@ public class DefaultCodegen {
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)
*
@ -2196,6 +2234,19 @@ public class DefaultCodegen {
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
*

View File

@ -263,6 +263,28 @@ public class DefaultGenerator extends AbstractGenerator implements Generator {
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);
}
@ -368,6 +390,29 @@ public class DefaultGenerator extends AbstractGenerator implements Generator {
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);
}

View File

@ -34,6 +34,8 @@ public class PerlClientCodegen extends DefaultCodegen implements CodegenConfig {
apiTemplateFiles.put("api.mustache", ".pm");
modelTestTemplateFiles.put("object_test.mustache", ".t");
apiTestTemplateFiles.put("api_test.mustache", ".t");
modelDocTemplateFiles.put("object_doc.mustache", ".md");
apiDocTemplateFiles.put("api_doc.mustache", ".md");
embeddedTemplateDir = templateDir = "perl";
@ -147,7 +149,6 @@ public class PerlClientCodegen extends DefaultCodegen implements CodegenConfig {
return (outputFolder + "/lib/" + modulePathPart + modelPackage()).replace('/', File.separatorChar);
}
@Override
public String apiTestFileFolder() {
return (outputFolder + "/t").replace('/', File.separatorChar);
@ -158,6 +159,16 @@ public class PerlClientCodegen extends DefaultCodegen implements CodegenConfig {
return (outputFolder + "/t").replace('/', File.separatorChar);
}
@Override
public String apiDocFileFolder() {
return (outputFolder).replace('/', File.separatorChar);
}
@Override
public String modelDocFileFolder() {
return (outputFolder).replace('/', File.separatorChar);
}
@Override
public String getTypeDeclaration(Property p) {
if (p instanceof ArrayProperty) {
@ -251,11 +262,21 @@ public class PerlClientCodegen extends DefaultCodegen implements CodegenConfig {
return toModelFilename(name) + "Test";
}
@Override
public String toModelDocFilename(String name) {
return toModelFilename(name);
}
@Override
public String toApiTestFilename(String name) {
return toApiFilename(name) + "Test";
}
@Override
public String toApiDocFilename(String name) {
return toApiFilename(name);
}
@Override
public String toApiFilename(String name) {
// replace - with _ e.g. created-at => created_at

View File

@ -8,7 +8,7 @@ WWW::SwaggerClient::Role - a Moose role for the Swagger Petstore
Automatically generated by the Perl Swagger Codegen project:
- Build date: 2016-03-04T14:39:09.479+08:00
- Build date: 2016-02-11T18:16:24.249+08:00
- Build package: class io.swagger.codegen.languages.PerlClientCodegen
- Codegen version:

View File

@ -37,7 +37,7 @@ has version_info => ( is => 'ro',
default => sub { {
app_name => 'Swagger Petstore',
app_version => '1.0.0',
generated_date => '2016-03-04T14:39:09.479+08:00',
generated_date => '2016-02-11T18:16:24.249+08:00',
generator_class => 'class io.swagger.codegen.languages.PerlClientCodegen',
} },
documentation => 'Information about the application version and the codegen codebase version'
@ -103,7 +103,7 @@ Automatically generated by the Perl Swagger Codegen project:
=over 4
=item Build date: 2016-03-04T14:39:09.479+08:00
=item Build date: 2016-02-11T18:16:24.249+08:00
=item Build package: class io.swagger.codegen.languages.PerlClientCodegen

View File

@ -25,6 +25,14 @@ $WWW::SwaggerClient::Configuration::password = 'password';
my $api = WWW::SwaggerClient::PetApi->new();
# exception handling
#eval {
# print "\nget_pet_by_id:".Dumper $api->get_pet_by_id(pet_id => 9999);
#};
#if ($@) {
# print "Exception when calling: $@\n";
#}
my $pet_id = 10008;
my $category = WWW::SwaggerClient::Object::Category->new('id' => '2', 'name' => 'perl');