add doc for api method

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

@@ -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();

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

@@ -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
      *

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

@@ -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);
                 }

modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/PerlClientCodegen.java

@@ -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

samples/client/petstore/perl/README.md

@@ -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: 
 

samples/client/petstore/perl/lib/WWW/SwaggerClient/Role.pm

@@ -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
 

samples/client/petstore/perl/test.pl

@@ -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');