[PHP] Add documentation (markdown) to APIs and models

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

@@ -32,6 +32,7 @@ public class CodegenOperation {
     public ExternalDocs externalDocs;
     public Map<String, Object> vendorExtensions;
     public String nickname; // legacy support
+    public String operationIdLowerCase; // for mardown documentation
 
     /**
      * Check if there's at least one parameter

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

@@ -1575,7 +1575,6 @@ public int compare(CodegenParameter one, CodegenParameter another) {
         // legacy support
         op.nickname = op.operationId;
 
-
         if (op.allParams.size() > 0) {
             op.hasParams = true;
         }
@@ -2075,6 +2074,7 @@ public void addOperationToGroup(String tag, String resourcePath, Operation opera
             LOGGER.warn("generated unique operationId `" + uniqueName + "`");
         }
         co.operationId = uniqueName;
+        co.operationIdLowerCase = uniqueName.toLowerCase();
         opList.add(co);
         co.baseName = tag;
     }

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

@@ -3,6 +3,7 @@
 import io.swagger.codegen.CliOption;
 import io.swagger.codegen.CodegenConfig;
 import io.swagger.codegen.CodegenConstants;
+import io.swagger.codegen.CodegenParameter;
 import io.swagger.codegen.CodegenType;
 import io.swagger.codegen.DefaultCodegen;
 import io.swagger.codegen.SupportingFile;
@@ -35,6 +36,8 @@ public class PhpClientCodegen extends DefaultCodegen implements CodegenConfig {
     protected String artifactVersion = "1.0.0";
     protected String srcBasePath = "lib";
     protected String variableNamingConvention= "snake_case";
+    protected String apiDocPath = "docs/";
+    protected String modelDocPath = "docs/";
 
     public PhpClientCodegen() {
         super();
@@ -49,6 +52,9 @@ public PhpClientCodegen() {
         modelPackage = invokerPackage + "\\Model";
         testPackage = invokerPackage + "\\Tests";
 
+        modelDocTemplateFiles.put("model_doc.mustache", ".md");
+        apiDocTemplateFiles.put("api_doc.mustache", ".md");
+
         setReservedWordsLowerCase(
                 Arrays.asList(
                     // local variables used in api methods (endpoints)
@@ -110,8 +116,8 @@ public PhpClientCodegen() {
         cliOptions.add(new CliOption(CodegenConstants.INVOKER_PACKAGE, "The main namespace to use for all classes. e.g. Yay\\Pets"));
         cliOptions.add(new CliOption(PACKAGE_PATH, "The main package name for classes. e.g. GeneratedPetstore"));
         cliOptions.add(new CliOption(SRC_BASE_PATH, "The directory under packagePath to serve as source root."));
-        cliOptions.add(new CliOption(COMPOSER_VENDOR_NAME, "The vendor name used in the composer package name. The template uses {{composerVendorName}}/{{composerProjectName}} for the composer package name. e.g. yaypets"));
-        cliOptions.add(new CliOption(COMPOSER_PROJECT_NAME, "The project name used in the composer package name. The template uses {{composerVendorName}}/{{composerProjectName}} for the composer package name. e.g. petstore-client"));
+        cliOptions.add(new CliOption(COMPOSER_VENDOR_NAME, "The vendor name used in the composer package name. The template uses {{composerVendorName}}/{{composerProjectName}} for the composer package name. e.g. yaypets. IMPORTANT NOTE (2016/03): composerVendorName will be deprecated and replaced by gitUserId in the next swagger-codegen release"));
+        cliOptions.add(new CliOption(COMPOSER_PROJECT_NAME, "The project name used in the composer package name. The template uses {{composerVendorName}}/{{composerProjectName}} for the composer package name. e.g. petstore-client. IMPORTANT NOTE (2016/03): composerProjectName will be deprecated and replaced by gitRepoId in the next swagger-codegen release"));
         cliOptions.add(new CliOption(CodegenConstants.ARTIFACT_VERSION, "The version to use in the composer package version field. e.g. 1.2.3"));
     }
 
@@ -217,6 +223,10 @@ public void processOpts() {
 
         additionalProperties.put("escapedInvokerPackage", invokerPackage.replace("\\", "\\\\"));
 
+        // make api and model doc path available in mustache template
+        additionalProperties.put("apiDocPath", apiDocPath);
+        additionalProperties.put("modelDocPath", modelDocPath);
+
         supportingFiles.add(new SupportingFile("configuration.mustache", toPackagePath(invokerPackage, srcBasePath), "Configuration.php"));
         supportingFiles.add(new SupportingFile("ApiClient.mustache", toPackagePath(invokerPackage, srcBasePath), "ApiClient.php"));
         supportingFiles.add(new SupportingFile("ApiException.mustache", toPackagePath(invokerPackage, srcBasePath), "ApiException.php"));
@@ -254,6 +264,28 @@ public String modelTestFileFolder() {
         return (outputFolder + "/" + toPackagePath(testPackage, srcBasePath));
     }
 
+    @Override
+    public String apiDocFileFolder() {
+        //return (outputFolder + "/" + apiDocPath).replace('/', File.separatorChar);
+        return (outputFolder + "/" + getPackagePath() + "/" + apiDocPath);
+    }
+
+    @Override
+    public String modelDocFileFolder() {
+        //return (outputFolder + "/" + modelDocPath).replace('/', File.separatorChar);
+        return (outputFolder + "/" + getPackagePath() + "/" + modelDocPath);
+    }
+
+    @Override
+    public String toModelDocFilename(String name) {
+        return toModelName(name);
+    }
+
+    @Override
+    public String toApiDocFilename(String name) {
+        return toApiName(name);
+    }
+
     @Override
     public String getTypeDeclaration(Property p) {
         if (p instanceof ArrayProperty) {
@@ -460,4 +492,69 @@ public String toDefaultValue(Property p) {
         return null;
     }
 
+    @Override
+    public void setParameterExampleValue(CodegenParameter p) {
+        String example;
+
+        if (p.defaultValue == null) {
+            example = p.example;
+        } else {
+            example = p.defaultValue;
+        }
+
+        String type = p.baseType;
+        if (type == null) {
+            type = p.dataType;
+        }
+
+        if ("String".equalsIgnoreCase(type)) {
+            if (example == null) {
+                example = p.paramName + "_example";
+            }
+            example = "\"" + escapeText(example) + "\"";
+        } else if ("Integer".equals(type) || "int".equals(type)) {
+            if (example == null) {
+                example = "56";
+            }
+        } else if ("Float".equalsIgnoreCase(type) || "Double".equalsIgnoreCase(type)) {
+            if (example == null) {
+                example = "3.4";
+            }
+        } else if ("BOOLEAN".equalsIgnoreCase(type) || "bool".equalsIgnoreCase(type)) {
+            if (example == null) {
+                example = "True";
+            }
+        } else if ("\\SplFileObject".equalsIgnoreCase(type)) {
+            if (example == null) {
+                example = "/path/to/file";
+            }
+            example = "\"" + escapeText(example) + "\"";
+        } else if ("Date".equalsIgnoreCase(type)) {
+            if (example == null) {
+                example = "2013-10-20";
+            }
+            example = "new \\DateTime(\"" + escapeText(example) + "\")";
+        } else if ("DateTime".equalsIgnoreCase(type)) {
+            if (example == null) {
+                example = "2013-10-20T19:20:30+01:00";
+            }
+            example = "new \\DateTime(\"" + escapeText(example) + "\")";
+        } else if (!languageSpecificPrimitives.contains(type)) {
+            // type is a model class, e.g. User
+            example = "new " + type + "()";
+        } else {
+            LOGGER.warn("Type " + type + " not handled properly in setParameterExampleValue");
+        }
+
+        if (example == null) {
+            example = "NULL";
+        } else if (Boolean.TRUE.equals(p.isListContainer)) {
+            example = "array(" + example + ")";
+        } else if (Boolean.TRUE.equals(p.isMapContainer)) {
+            example = "array('key' => " + example + ")";
+        }
+
+        p.example = example;
+    }
+
 }

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

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

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

@@ -14,11 +14,11 @@ You can install the bindings via [Composer](http://getcomposer.org/). Add this t
   "repositories": [
     {
       "type": "git",
-      "url": "https://github.com/{{composerVendorName}}/{{composerProjectName}}.git"
+      "url": "https://github.com/{{#gitUserId}}{{.}}{{/gitUserId}}{{^gitUserId}}{{composerVendorName}}{{/gitUserId}}/{{#gitRepoId}}{{.}}{{/gitRepoId}}{{^gitRepoId}}{{composerProjectName}}{{/gitRepoId}}.git"
     }
   ],
   "require": {
-    "{{composerVendorName}}/{{composerProjectName}}": "*@dev"
+    "{{#gitUserId}}{{.}}{{/gitUserId}}{{^gitUserId}}{{composerVendorName}}{{/gitUserId}}/{{#gitRepoId}}{{.}}{{/gitRepoId}}{{^gitRepoId}}{{composerProjectName}}{{/gitRepoId}}": "*@dev"
   }
 }
 ```
@@ -40,6 +40,42 @@ composer install
 ./vendor/bin/phpunit lib/Tests
 ```
 
+## Documentation for API Endpoints
+
+All URIs are relative to *{{basePath}}*
+
+Class | Method | HTTP request | Description
+------------ | ------------- | ------------- | -------------
+{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{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}}}
+- **Authorizatoin URL**: {{{authorizationUrl}}}
+- **Scopes**: {{^scopes}}N/A{{/scopes}}
+{{#scopes}} - **{{{scope}}}**: {{{description}}}
+{{/scopes}}
+{{/isOAuth}}
+
+{{/authMethods}}
+
 ## Author
 
 {{#apiInfo}}{{#apis}}{{^hasMore}}{{infoEmail}}

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

@@ -0,0 +1,72 @@
+# {{invokerPackage}}\{{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 
+```php
+<?php
+require_once(__DIR__ . '/vendor/autoload.php');
+{{#hasAuthMethods}}{{#authMethods}}{{#isBasic}}
+// Configure HTTP basic authorization: {{{name}}}
+{{{invokerPackage}}}::getDefaultConfiguration->setUsername('YOUR_USERNAME');
+{{{invokerPackage}}}::getDefaultConfiguration->setPassword('YOUR_PASSWORD');{{/isBasic}}{{#isApiKey}}
+// Configure API key authorization: {{{name}}}
+{{{invokerPackage}}}::getDefaultConfiguration->setApiKey('{{{keyParamName}}}', 'YOUR_API_KEY');
+// Uncomment below to setup prefix (e.g. BEARER) for API key, if needed
+// {{{invokerPackage}}}::getDefaultConfiguration->setApiKeyPrefix('{{{keyParamName}}}', 'BEARER');{{/isApiKey}}{{#isOAuth}}
+// Configure OAuth2 access token for authorization: {{{name}}}
+{{{invokerPackage}}}::getDefaultConfiguration->setAccessToken('YOUR_ACCESS_TOKEN');{{/isOAuth}}{{/authMethods}}
+{{/hasAuthMethods}}
+
+$api_instance = new {{invokerPackage}}\{{classname}}();
+{{#allParams}}${{paramName}} = {{{example}}}; // {{{dataType}}} | {{{description}}}
+{{/allParams}}
+
+try { 
+    {{#returnType}}$result = {{/returnType}}$api_instance->{{{operationId}}}({{#allParams}}${{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}});{{#returnType}}
+    print_r($result);{{/returnType}}
+} catch (Exception $e) {
+    echo 'Exception when calling {{classname}}->{{operationId}}: ', $e->getMessage(), "\n";
+}
+?>
+```
+
+### 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 reuqest headers
+
+ - **Content-Type**: {{#consumes}}{{mediaType}}{{#hasMore}}, {{/hasMore}}{{/consumes}}{{^consumes}}Not defined{{/consumes}}
+ - **Accept**: {{#produces}}{{mediaType}}{{#hasMore}}, {{/hasMore}}{{/produces}}{{^produces}}Not defined{{/produces}}
+
+[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
+
+{{/operation}}
+{{/operations}}

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

@@ -1,5 +1,5 @@
 {
-    "name": "{{composerVendorName}}/{{composerProjectName}}",{{#artifactVersion}}
+    "name": "{{#gitUserId}}{{.}}{{/gitUserId}}{{^gitUserId}}{{composerVendorName}}{{/gitUserId}}/{{#gitRepoId}}{{.}}{{/gitRepoId}}{{^gitRepoId}}{{composerProjectName}}{{/gitRepoId}}",{{#artifactVersion}}
     "version": "{{artifactVersion}}",{{/artifactVersion}}
     "description": "{{description}}",
     "keywords": [

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

@@ -0,0 +1,11 @@
+{{#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}}
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+{{/model}}{{/models}}

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

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

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-13T22:43:11.863+08:00
+- Build date: 2016-03-16T15:35:49.140+08:00
 - Build package: class io.swagger.codegen.languages.PerlClientCodegen
 - Codegen version: 
 
@@ -329,8 +329,8 @@ Class | Method | HTTP request | Description
 - **Flow**: implicit
 - **Authorizatoin URL**: http://petstore.swagger.io/api/oauth/dialog
 - **Scopes**: 
- - **write:pets**: modify pets in your account
- - **read:pets**: read your pets
+  - **write:pets**: modify pets in your account
+  - **read:pets**: read your pets
 
 
 

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-13T22:43:11.863+08:00',
+                          generated_date => '2016-03-16T15:35:49.140+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-13T22:43:11.863+08:00
+=item Build date: 2016-03-16T15:35:49.140+08:00
 
 =item Build package: class io.swagger.codegen.languages.PerlClientCodegen