[CSharp] Add auto-generated CSharp documentation in Markdown

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

@@ -11,6 +11,7 @@
 import io.swagger.codegen.CodegenProperty;
 import io.swagger.codegen.CodegenModel;
 import io.swagger.codegen.CodegenOperation;
+import io.swagger.codegen.CodegenParameter;
 import io.swagger.models.properties.*;
 import io.swagger.codegen.CliOption;
 import io.swagger.models.Model;
@@ -45,6 +46,8 @@ public class CSharpClientCodegen extends AbstractCSharpCodegen {
     protected String packageCopyright = "No Copyright";
     protected String clientPackage = "IO.Swagger.Client";
     protected String localVariablePrefix = "";
+    protected String apiDocPath = "docs/";
+    protected String modelDocPath = "docs/";
 
     protected String targetFramework = NET45;
     protected String targetFrameworkNuget = "net45";
@@ -62,6 +65,9 @@ public CSharpClientCodegen() {
         modelTestTemplateFiles.put("model_test.mustache", ".cs");
         apiTestTemplateFiles.put("api_test.mustache", ".cs");
 
+        modelDocTemplateFiles.put("model_doc.mustache", ".md");
+        apiDocTemplateFiles.put("api_doc.mustache", ".md");
+
         // C# client default
         setSourceFolder("src" + File.separator + "main" + File.separator + "csharp");
 
@@ -219,17 +225,19 @@ public void processOpts() {
         supportingFiles.add(new SupportingFile("compile.mustache", "", "compile.bat"));
         supportingFiles.add(new SupportingFile("compile-mono.sh.mustache", "", "compile-mono.sh"));
         supportingFiles.add(new SupportingFile("packages.config.mustache", "vendor" + java.io.File.separator, "packages.config"));
-        supportingFiles.add(new SupportingFile("README.md", "", "README.md"));
+        supportingFiles.add(new SupportingFile("README.mustache", "", "README.md"));
         supportingFiles.add(new SupportingFile("git_push.sh.mustache", "", "git_push.sh"));
         supportingFiles.add(new SupportingFile("gitignore.mustache", "", ".gitignore"));
 
-
         if (optionalAssemblyInfoFlag) {
             supportingFiles.add(new SupportingFile("AssemblyInfo.mustache", packageFolder + File.separator + "Properties", "AssemblyInfo.cs"));
         }
         if (optionalProjectFileFlag) {
             supportingFiles.add(new SupportingFile("Project.mustache", packageFolder, clientPackage + ".csproj"));
         }
+
+        additionalProperties.put("apiDocPath", apiDocPath);
+        additionalProperties.put("modelDocPath", modelDocPath);
     }
 
     @Override
@@ -300,20 +308,20 @@ public void setPackageGuid(String packageGuid) {
 
     @Override
     public Map<String, Object> postProcessModels(Map<String, Object> objMap) {
-    	Map<String, Object> objs = super.postProcessModels(objMap);
-    	
+        Map<String, Object> objs = super.postProcessModels(objMap);
+
         List<Object> models = (List<Object>) objs.get("models");
         for (Object _mo : models) {
             Map<String, Object> mo = (Map<String, Object>) _mo;
             CodegenModel cm = (CodegenModel) mo.get("model");
             for (CodegenProperty var : cm.vars) {
                 Map<String, Object> allowableValues = var.allowableValues;
-                
+
                 // handle ArrayProperty
                 if (var.items != null) {
                     allowableValues = var.items.allowableValues;
                 }
-                
+
                 if (allowableValues == null) {
                     continue;
                 }
@@ -349,12 +357,12 @@ public Map<String, Object> postProcessModels(Map<String, Object> objMap) {
                 if (var.datatypeWithEnum != null) {
                     var.vendorExtensions.put(DATA_TYPE_WITH_ENUM_EXTENSION, var.datatypeWithEnum.substring(0, var.datatypeWithEnum.length() - 1));
                 }
-                
+
                 if (var.defaultValue != null) {
                     String enumName = null;
-                    
+
                     for (Map<String, String> enumVar : enumVars) {
-                    	
+
                         if (var.defaultValue.replace("\"", "").equals(enumVar.get("value"))) {
                             enumName = enumVar.get("name");
                             break;
@@ -413,7 +421,7 @@ private CodegenModel reconcileInlineEnums(CodegenModel codegenModel, CodegenMode
                     }
                 }
             }
-            
+
             if(removedChildEnum) {
                 // If we removed an entry from this model's vars, we need to ensure hasMore is updated
                 int count = 0, numVars = codegenProperties.size();
@@ -467,4 +475,20 @@ public void setSupportsAsync(Boolean supportsAsync){
     public void setSupportsUWP(Boolean supportsUWP){
         this.supportsUWP = supportsUWP;
     }
+
+    @Override
+    public String toModelDocFilename(String name) {
+        return toModelFilename(name);
+    }
+
+    @Override
+    public String apiDocFileFolder() {
+        return (outputFolder + "/" + apiDocPath).replace('/', File.separatorChar);
+    }
+
+    @Override
+    public String modelDocFileFolder() {
+        return (outputFolder + "/" + modelDocPath).replace('/', File.separatorChar);
+    }
+
 }

modules/swagger-codegen/src/main/resources/Javascript/README.mustache

@@ -129,7 +129,7 @@ Class | Method | HTTP request | Description
 {{/isBasic}}
 {{#isOAuth}}- **Type**: OAuth
 - **Flow**: {{flow}}
-- **Authorizatoin URL**: {{authorizationUrl}}
+- **Authorization URL**: {{authorizationUrl}}
 - **Scopes**: {{^scopes}}N/A{{/scopes}}
 {{#scopes}}  - {{scope}}: {{description}}
 {{/scopes}}

modules/swagger-codegen/src/main/resources/csharp/README.mustache

@@ -0,0 +1,120 @@
+{{moduleName}} - the C# library for the {{appName}}
+
+{{#appDescription}}
+    {{{appDescription}}}
+{{/appDescription}}
+
+This SDK is automatically generated by the [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) project:
+
+- API version: {{appVersion}}
+- Package version: {{gemVersion}}
+- Build date: {{generatedDate}}
+- Build package: {{generatorClass}}
+{{#infoUrl}}
+    For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
+{{/infoUrl}}
+
+## Frameworks supported
+- .NET 4.0 or later
+- Windows Phone 7.1 (Mango)
+
+## Dependencies
+- [RestSharp] (https://www.nuget.org/packages/RestSharp) - 105.1.0 or later
+- [Json.NET] (https://www.nuget.org/packages/Newtonsoft.Json/) - 7.0.0 or later
+
+The DLLs included in the package may not be the latest version. We recommned using [NuGet] (https://docs.nuget.org/consume/installing-nuget) to obtain the latest version of the packages:
+```
+Install-Package RestSharp
+Install-Package Newtonsoft.Json
+```
+
+NOTE: RestSharp versions greater than 105.1.0 have a bug which causes file uploads to fail. See [RestSharp#742](https://github.com/restsharp/RestSharp/issues/742)
+
+## Installation
+Run the following command to generate the DLL
+- [Mac/Linux] compile-mono.sh
+- [Windows] compile.bat
+
+Then include the DLL (under the `bin` folder) in the C# project
+
+
+```csharp
+using System;
+using System.Diagnostics;
+using {{packageName}}.Api;
+using {{packageName}}.Client;
+using {{packageName}}.Module;
+
+namespace Example
+{
+    public class {{operationId}}Example
+    {
+        public void main(){
+            {{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}{{#hasAuthMethods}}{{#authMethods}}{{#isBasic}}
+                // Configure HTTP basic authorization: {{{name}}}
+                Configuration.Default.Username = 'YOUR_USERNAME';
+                Configuration.Default.Password = 'YOUR_PASSWORD';{{/isBasic}}{{#isApiKey}}
+                // Configure API key authorization: {{{name}}}
+                Configuration.Default.ApiKey.Add('{{{keyParamName}}}', 'YOUR_API_KEY');
+                // Uncomment below to setup prefix (e.g. BEARER) for API key, if needed
+                // Configuration.Default.ApiKeyPrefix.Add('{{{keyParamName}}}', 'BEARER');{{/isApiKey}}{{#isOAuth}}
+                // Configure OAuth2 access token for authorization: {{{name}}}
+                Configuration.Default.AccessToken = 'YOUR_ACCESS_TOKEN';{{/isOAuth}}{{/authMethods}}
+            {{/hasAuthMethods}}
+
+                var apiInstance = new {{classname}}();
+            {{#allParams}}
+                {{#isPrimitiveType}}
+                var {{paramName}} = {{example}};  // {{{dataType}}} | {{{description}}}
+                {{/isPrimitiveType}}
+                {{^isPrimitiveType}}
+                var {{paramName}} = new {{{dataType}}}(); // {{{dataType}}} | {{{description}}}
+                {{/isPrimitiveType}}
+            {{/allParams}}
+
+            try {
+            {{#returnType}}{{returnType}} result = {{/returnType}}apiInstance.{{{operationId}}}({{#allParams}}{{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}});{{#returnType}}
+                Debug.WriteLine(result);{{/returnType}}
+            } catch (Exception e) {
+                Debug.Print("Exception when calling {{classname}}.{{operationId}}: " + e.Message );
+            }
+        }
+    }
+}{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
+```
+
+## Documentation for API Endpoints
+
+All URIs are relative to *{{basePath}}*
+
+Class | Method | HTTP request | Description
+------------ | ------------- | ------------- | -------------
+{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{{summary}}}{{/summary}}
+{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
+
+## Documentation for Models
+
+{{#models}}{{#model}} - [{{classname}}]({{modelDocPath}}{{classname}}.md)
+{{/model}}{{/models}}
+
+## Documentation for Authorization
+
+{{^authMethods}} All endpoints do not require authorization.
+{{/authMethods}}{{#authMethods}}{{#last}} Authentication schemes defined for the API:{{/last}}{{/authMethods}}
+{{#authMethods}}### {{name}}
+
+{{#isApiKey}}- **Type**: API key
+- **API key parameter name**: {{keyParamName}}
+- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
+{{/isApiKey}}
+{{#isBasic}}- **Type**: HTTP basic authentication
+{{/isBasic}}
+{{#isOAuth}}- **Type**: OAuth
+- **Flow**: {{flow}}
+- **Authorization URL**: {{authorizationUrl}}
+- **Scopes**: {{^scopes}}N/A{{/scopes}}
+{{#scopes}}  - {{scope}}: {{description}}
+{{/scopes}}
+{{/isOAuth}}
+
+{{/authMethods}}

modules/swagger-codegen/src/main/resources/csharp/api_doc.mustache

@@ -0,0 +1,87 @@
+# {{packageName}}.Api.{{classname}}{{#description}}
+{{description}}{{/description}}
+
+All URIs are relative to *{{basePath}}*
+
+Method | HTTP request | Description
+------------- | ------------- | -------------
+{{#operations}}{{#operation}}[**{{operationId}}**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
+{{/operation}}{{/operations}}
+
+{{#operations}}
+{{#operation}}
+# **{{{operationId}}}**
+> {{#returnType}}{{{returnType}}} {{/returnType}}{{{operationId}}}({{#allParams}}{{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}})
+
+{{{summary}}}{{#notes}}
+
+{{{notes}}}{{/notes}}
+
+### Example 
+```csharp
+using System;
+using System.Diagnostics;
+using {{packageName}}.Api;
+using {{packageName}}.Client;
+using {{packageName}}.Module;
+
+namespace Example
+{
+    public class {{operationId}}Example
+    {
+        public void main(){
+            {{#hasAuthMethods}}{{#authMethods}}{{#isBasic}}
+            // Configure HTTP basic authorization: {{{name}}}
+            Configuration.Default.Username = 'YOUR_USERNAME';
+            Configuration.Default.Password = 'YOUR_PASSWORD';{{/isBasic}}{{#isApiKey}}
+            // Configure API key authorization: {{{name}}}
+            Configuration.Default.ApiKey.Add('{{{keyParamName}}}', 'YOUR_API_KEY');
+            // Uncomment below to setup prefix (e.g. BEARER) for API key, if needed
+            // Configuration.Default.ApiKeyPrefix.Add('{{{keyParamName}}}', 'BEARER');{{/isApiKey}}{{#isOAuth}}
+            // Configure OAuth2 access token for authorization: {{{name}}}
+            Configuration.Default.AccessToken = 'YOUR_ACCESS_TOKEN';{{/isOAuth}}{{/authMethods}}
+            {{/hasAuthMethods}}
+
+            var apiInstance = new {{classname}}();
+            {{#allParams}}
+            {{#isPrimitiveType}}
+            var {{paramName}} = {{example}};  // {{{dataType}}} | {{{description}}}
+            {{/isPrimitiveType}}
+            {{^isPrimitiveType}}
+            var {{paramName}} = new {{{dataType}}}(); // {{{dataType}}} | {{{description}}}
+            {{/isPrimitiveType}}
+            {{/allParams}}
+
+            try {
+                {{#returnType}}{{returnType}} result = {{/returnType}}apiInstance.{{{operationId}}}({{#allParams}}{{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}});{{#returnType}}
+                Debug.WriteLine(result);{{/returnType}}
+            } catch (Exception e) {
+                Debug.Print("Exception when calling {{classname}}.{{operationId}}: " + e.Message );
+            }
+        }
+    }
+}
+```
+
+### Parameters
+{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------{{/-last}}{{/allParams}}
+{{#allParams}} **{{paramName}}** | {{#isFile}}**{{dataType}}**{{/isFile}}{{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{^isFile}}[**{{dataType}}**]({{baseType}}.md){{/isFile}}{{/isPrimitiveType}}| {{description}} | {{^required}}[optional] {{/required}}{{#defaultValue}}[default to {{defaultValue}}]{{/defaultValue}}
+{{/allParams}}
+
+### Return type
+
+{{#returnType}}{{#returnTypeIsPrimitive}}**{{{returnType}}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}[**{{{returnType}}}**]({{returnBaseType}}.md){{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}void (empty response body){{/returnType}}
+
+### Authorization
+
+{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{{name}}}](../README.md#{{{name}}}){{^-last}}, {{/-last}}{{/authMethods}}
+
+### HTTP request headers
+
+ - **Content-Type**: {{#consumes}}{{mediaType}}{{#hasMore}}, {{/hasMore}}{{/consumes}}{{^consumes}}Not defined{{/consumes}}
+ - **Accept**: {{#produces}}{{mediaType}}{{#hasMore}}, {{/hasMore}}{{/produces}}{{^produces}}Not defined{{/produces}}
+
+{{/operation}}
+{{/operations}}

modules/swagger-codegen/src/main/resources/csharp/model_doc.mustache

@@ -0,0 +1,10 @@
+{{#models}}{{#model}}# {{classname}}
+
+## Properties
+
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+{{#vars}}**{{name}}** | {{#isPrimitiveType}}**{{datatype}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{datatype}}**]({{complexType}}.md){{/isPrimitiveType}} | {{description}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}}
+{{/vars}}
+
+{{/model}}{{/models}}

modules/swagger-codegen/src/main/resources/objc/README.mustache

@@ -135,7 +135,7 @@ Class | Method | HTTP request | Description
 {{/isBasic}}
 {{#isOAuth}}- **Type**: OAuth
 - **Flow**: {{{flow}}}
-- **Authorizatoin URL**: {{{authorizationUrl}}}
+- **Authorization URL**: {{{authorizationUrl}}}
 - **Scopes**: {{^scopes}}N/A{{/scopes}}
 {{#scopes}} - **{{{scope}}}**: {{{description}}}
 {{/scopes}}

modules/swagger-codegen/src/main/resources/perl/README.mustache

@@ -303,7 +303,7 @@ Class | Method | HTTP request | Description
 {{/isBasic}}
 {{#isOAuth}}- **Type**: OAuth
 - **Flow**: {{{flow}}}
-- **Authorizatoin URL**: {{{authorizationUrl}}}
+- **Authorization URL**: {{{authorizationUrl}}}
 - **Scopes**: {{^scopes}}N/A{{/scopes}}
 {{#scopes}}  - **{{{scope}}}**: {{{description}}}
 {{/scopes}}

modules/swagger-codegen/src/main/resources/php/README.mustache

@@ -116,7 +116,7 @@ Class | Method | HTTP request | Description
 {{/isBasic}}
 {{#isOAuth}}- **Type**: OAuth
 - **Flow**: {{{flow}}}
-- **Authorizatoin URL**: {{{authorizationUrl}}}
+- **Authorization URL**: {{{authorizationUrl}}}
 - **Scopes**: {{^scopes}}N/A{{/scopes}}
 {{#scopes}} - **{{{scope}}}**: {{{description}}}
 {{/scopes}}