Merge pull request #2482 from wing328/objc_doc

[ObjC] Add auto-generated documentation (markdown) to ObjC API client

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

@@ -4,6 +4,7 @@ import io.swagger.codegen.CliOption;
 import io.swagger.codegen.CodegenConfig;
 import io.swagger.codegen.CodegenConstants;
 import io.swagger.codegen.CodegenOperation;
+import io.swagger.codegen.CodegenParameter;
 import io.swagger.codegen.CodegenProperty;
 import io.swagger.codegen.CodegenType;
 import io.swagger.codegen.DefaultCodegen;
@@ -36,6 +37,8 @@ public class ObjcClientCodegen extends DefaultCodegen implements CodegenConfig {
     protected String license = "MIT";
     protected String gitRepoURL = "https://github.com/swagger-api/swagger-codegen";
     protected String[] specialWords = {"new", "copy"};
+    protected String apiDocPath = "docs/";
+    protected String modelDocPath = "docs/";
 
     public ObjcClientCodegen() {
         super();
@@ -46,6 +49,8 @@ public class ObjcClientCodegen extends DefaultCodegen implements CodegenConfig {
         apiTemplateFiles.put("api-header.mustache", ".h");
         apiTemplateFiles.put("api-body.mustache", ".m");
         embeddedTemplateDir = templateDir = "objc";
+        modelDocTemplateFiles.put("model_doc.mustache", ".md");
+        apiDocTemplateFiles.put("api_doc.mustache", ".md");
 
         defaultIncludes.clear();
         defaultIncludes.add("bool");
@@ -199,6 +204,10 @@ public class ObjcClientCodegen extends DefaultCodegen implements CodegenConfig {
         additionalProperties.put(GIT_REPO_URL, gitRepoURL);
         additionalProperties.put(LICENSE, license);
 
+        // make api and model doc path available in mustache template
+        additionalProperties.put("apiDocPath", apiDocPath);
+        additionalProperties.put("modelDocPath", modelDocPath);
+
         String swaggerFolder = podName;
 
         modelPackage = swaggerFolder;
@@ -388,6 +397,26 @@ public class ObjcClientCodegen extends DefaultCodegen implements CodegenConfig {
         return name;
     }
 
+    @Override
+    public String apiDocFileFolder() {
+        return (outputFolder + "/" + apiDocPath).replace("/", File.separator);
+    }
+ 
+    @Override
+    public String modelDocFileFolder() {
+        return (outputFolder + "/" + modelDocPath).replace("/", File.separator);
+    }
+ 
+    @Override
+    public String toModelDocFilename(String name) {
+        return toModelName(name);
+    }
+ 
+    @Override
+    public String toApiDocFilename(String name) {
+        return toApiName(name);
+    }
+
     @Override
     public String apiFileFolder() {
         return outputFolder + File.separatorChar + apiPackage();
@@ -562,4 +591,75 @@ public class ObjcClientCodegen extends DefaultCodegen implements CodegenConfig {
         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 ("NSString*".equalsIgnoreCase(type)) {
+            if (example == null) {
+                example = p.paramName + "_example";
+            }
+            example = "@\"" + escapeText(example) + "\"";
+        } else if ("NSNumber*".equals(type)) {
+            if (example == null) {
+                example = "56";
+            }
+            example = "@" + example;
+        /* OBJC uses NSNumber to represent both int, long, double and float
+        } 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 ("NSURL*".equalsIgnoreCase(type)) {
+            if (example == null) {
+                example = "/path/to/file";
+            }
+            //[NSURL fileURLWithPath:@"path/to/file"]
+            example = "[NSURL fileURLWithPath:@\"" + escapeText(example) + "\"]";
+        /*} else if ("NSDate".equalsIgnoreCase(type)) {
+            if (example == null) {
+                example = "2013-10-20";
+            }
+            example = "'" + escapeText(example) + "'";*/
+        } else if ("NSDate*".equalsIgnoreCase(type)) {
+            if (example == null) {
+                example = "2013-10-20T19:20:30+01:00";
+            }
+            example = "@\"" + escapeText(example) + "\"";
+        } else if (!languageSpecificPrimitives.contains(type)) {
+            // type is a model class, e.g. User
+            type = type.replace("*", "");
+            // e.g. [[SWGPet alloc] init
+            example = "[[" + type + " alloc] init]";
+        } else {
+            LOGGER.warn("Type " + type + " not handled properly in setParameterExampleValue");
+        }
+
+        if (example == null) {
+            example = "NULL";
+        } else if (Boolean.TRUE.equals(p.isListContainer)) {
+            example = "@[" + example + "]";
+        } else if (Boolean.TRUE.equals(p.isMapContainer)) {
+            example = "@{@\"key\" : " + example + "}";
+        }
+
+        p.example = example;
+    }
+
+
 }

modules/swagger-codegen/src/main/resources/objc/ApiClient-body.mustache

@@ -716,11 +716,11 @@ static void (^reachabilityChangeBlock)(int);
     for (NSString *auth in authSettings) {
         NSDictionary *authSetting = [[config authSettings] objectForKey:auth];
 
-        if (authSetting) {
+        if (authSetting) { // auth setting is set only if the key is non-empty
-            if ([authSetting[@"in"] isEqualToString:@"header"]) {
+            if ([authSetting[@"in"] isEqualToString:@"header"] && [authSetting[@"key"] length] != 0) {
                 [headersWithAuth setObject:authSetting[@"value"] forKey:authSetting[@"key"]];
             }
-            else if ([authSetting[@"in"] isEqualToString:@"query"]) {
+            else if ([authSetting[@"in"] isEqualToString:@"query"] && [authSetting[@"key"] length] != 0) {
                 [querysWithAuth setObject:authSetting[@"value"] forKey:authSetting[@"key"]];
             }
         }

modules/swagger-codegen/src/main/resources/objc/Configuration-body.mustache

@@ -29,6 +29,7 @@
         self.host = @"{{basePath}}";
         self.username = @"";
         self.password = @"";
+        self.accessToken= @"";
         self.tempFolderPath = nil;
         self.debug = NO;
         self.verifySSL = YES;
@@ -42,18 +43,23 @@
 #pragma mark - Instance Methods
 
 - (NSString *) getApiKeyWithPrefix:(NSString *)key {
-    if ([self.apiKeyPrefix objectForKey:key] && [self.apiKey objectForKey:key]) {
+    if ([self.apiKeyPrefix objectForKey:key] && [self.apiKey objectForKey:key] != (id)[NSNull null] && [[self.apiKey objectForKey:key] length] != 0) { // both api key prefix and api key are set 
         return [NSString stringWithFormat:@"%@ %@", [self.apiKeyPrefix objectForKey:key], [self.apiKey objectForKey:key]];
     }
-    else if ([self.apiKey objectForKey:key]) {
+    else if ([self.apiKey objectForKey:key] != (id)[NSNull null] && [[self.apiKey objectForKey:key] length] != 0) { // only api key, no api key prefix
         return [NSString stringWithFormat:@"%@", [self.apiKey objectForKey:key]];
     }
-    else {
+    else { // return empty string if nothing is set
         return @"";
     }
 }
 
 - (NSString *) getBasicAuthToken {
+    // return empty string if username and password are empty
+    if (self.username.length == 0 && self.password.length == 0){
+        return  @"";
+    }
+
     NSString *basicAuthCredentials = [NSString stringWithFormat:@"%@:%@", self.username, self.password];
     NSData *data = [basicAuthCredentials dataUsingEncoding:NSUTF8StringEncoding];
     basicAuthCredentials = [NSString stringWithFormat:@"Basic %@", [data base64EncodedStringWithOptions:0]];
@@ -61,6 +67,15 @@
     return basicAuthCredentials;
 }
 
+- (NSString *) getAccessToken {
+    if (self.accessToken.length == 0) { // token not set, return empty string
+        return @"";
+    }
+    else {
+        return [NSString stringWithFormat:@"BEARER %@", self.accessToken];
+    }
+}
+
 #pragma mark - Setter Methods
 
 - (void) setApiKey:(NSString *)apiKey forApiKeyIdentifier:(NSString *)identifier {
@@ -126,6 +141,15 @@
                        @"value": [self getBasicAuthToken]
                    },
 {{/isBasic}}
+{{#isOAuth}}
+               @"{{name}}":
+                   @{
+                       @"type": @"oauth",
+                       @"in": @"header",
+                       @"key": @"Authorization",
+                       @"value": [self getAccessToken]
+                   },
+{{/isOAuth}}
 {{/authMethods}}
                };
 }

modules/swagger-codegen/src/main/resources/objc/Configuration-header.mustache

@@ -46,6 +46,11 @@
  */
 @property (nonatomic) NSString *password;
 
+/**
+ * Access token for OAuth
+ */
+@property (nonatomic) NSString *accessToken;
+
 /**
  * Temp folder for file download
  */
@@ -132,6 +137,11 @@
  */
 - (NSString *) getBasicAuthToken;
 
+/**
+ * Gets OAuth access token
+ */
+- (NSString *) getAccessToken;
+
 /**
  * Gets Authentication Setings
  */

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

@@ -1,20 +1,147 @@
 # {{podName}}
 
+{{#appDescription}}
+{{{appDescription}}}
+{{/appDescription}}
+
+This ObjC package is automatically generated by the [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) project:
+
+- API version: {{appVersion}}
+- Package version: {{artifactVersion}}
+- Build date: {{generatedDate}}
+- Build package: {{generatorClass}}
+{{#infoUrl}}
+For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
+{{/infoUrl}}
+
 ## Requirements
 
-The API client library requires ARC (Automatic Reference Counting) to be enabled in your Xcode project.
+The SDK requires [**ARC (Automatic Reference Counting)**](http://stackoverflow.com/questions/7778356/how-to-enable-disable-automatic-reference-counting) to be enabled in the Xcode project.
 
-## Installation
+## Installation & Usage
+### Install from Github using [CocoaPods](https://cocoapods.org/)
 
-To install it, put the API client library in your project and then simply add the following line to your Podfile:
+Add the following to the Podfile:
 
 ```ruby
-pod "{{podName}}", :path => "/path/to/lib"
+pod '{{podName}}', :git => 'https://github.com/{{gitUserId}}/{{gitRepoId}}.git'
+```
+
+To specify a particular branch, append `, :branch => 'branch-name-here'`
+
+To specify a particular commit, append `, :commit => '11aa22'`
+
+### Install from local path using [CocoaPods](https://cocoapods.org/)
+
+Put the SDK under your project folder (e.g. /path/to/objc_project/Vendor/{{podName}}) and then add the following to the Podfile:
+
+```ruby
+pod '{{podName}}', :path => 'Vendor/{{podName}}'
+```
+
+### Usage
+
+Import the following:
+```objc
+#import <{{podName}}/{{{classPrefix}}}ApiClient.h>
+#import <{{podName}}/{{{classPrefix}}}Configuration.h>
+// load models
+{{#models}}{{#model}}#import <{{podName}}/{{{classname}}}.h>
+{{/model}}{{/models}}// load API classes for accessing endpoints
+{{#apiInfo}}{{#apis}}#import <{{podName}}/{{{classname}}}.h>
+{{/apis}}{{/apiInfo}}
 ```
 
 ## Recommendation
 
-It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issue.
+It's recommended to create an instance of ApiClient per thread in a multi-threaded environment to avoid any potential issue.
+
+## Getting Started
+
+Please follow the [installation procedure](#installation--usage) and then run the following:
+
+```objc
+{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
+{{#hasAuthMethods}}
+{{classPrefix}}Configuration *apiConfig = [{{classPrefix}}Configuration sharedConfig];
+{{#authMethods}}{{#isBasic}}// Configure HTTP basic authorization (authentication scheme: {{{name}}})
+[apiConfig setUsername:@"YOUR_USERNAME"];
+[apiConfig setPassword:@"YOUR_PASSWORD"];
+{{/isBasic}}{{#isApiKey}}
+// Configure API key authorization: (authentication scheme: {{{name}}})
+[apiConfig setApiKey:@"YOUR_API_KEY" forApiKeyIdentifier:@"{{{keyParamName}}}"];
+// Uncomment below to setup prefix (e.g. BEARER) for API key, if needed
+//[apiConfig setApiKeyPrefix:@"BEARER" forApiKeyIdentifier:@"{{{keyParamName}}}"];
+{{/isApiKey}}{{#isOAuth}}
+// Configure OAuth2 access token for authorization: (authentication scheme: {{{name}}})
+[apiConfig setAccessToken:@"YOUR_ACCESS_TOKEN"];
+{{/isOAuth}}{{/authMethods}}
+{{/hasAuthMethods}}
+
+{{#allParams}}{{{dataType}}} *{{paramName}} = {{{example}}}; // {{{description}}}{{^required}} (optional){{/required}}{{#defaultValue}} (default to {{{.}}}){{/defaultValue}}
+{{/allParams}}
+
+@try
+{
+    {{classname}} *apiInstance = [[{{classname}} alloc] init];
+
+{{#summary}}    // {{{.}}}
+{{/summary}}    [apiInstance {{#vendorExtensions.x-objc-operationId}}{{vendorExtensions.x-objc-operationId}}{{/vendorExtensions.x-objc-operationId}}{{^vendorExtensions.x-objc-operationId}}{{nickname}}{{#hasParams}}With{{vendorExtensions.firstParamAltName}}{{/hasParams}}{{^hasParams}}WithCompletionHandler: {{/hasParams}}{{/vendorExtensions.x-objc-operationId}}{{#allParams}}{{#secondaryParam}}
+    {{paramName}}{{/secondaryParam}}:{{paramName}}{{/allParams}}
+              {{#hasParams}}completionHandler: {{/hasParams}}^({{#returnBaseType}}{{{returnType}}} output, {{/returnBaseType}}NSError* error)) {
+{{#returnType}}
+                            if (output) {
+                                NSLog(@"%@", output);
+                            }
+{{/returnType}}
+                            if (error) {
+                                NSLog(@"Error: %@", error);
+                            }
+                        }];
+}
+@catch (NSException *exception)
+{
+    NSLog(@"Exception when calling {{classname}}->{{operationId}}: %@ ", exception.name);
+    NSLog(@"Reason: %@ ", exception.reason);
+}
+{{/-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#{{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
 

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

@@ -0,0 +1,93 @@
+# {{classname}}{{#description}}
+{{description}}{{/description}}
+
+All URIs are relative to *{{basePath}}*
+
+Method | HTTP request | Description
+------------- | ------------- | -------------
+{{#operations}}{{#operation}}[**{{operationId}}**]({{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
+{{/operation}}{{/operations}}
+
+{{#operations}}
+{{#operation}}
+# **{{{operationId}}}**
+```objc
+-(NSNumber*) {{#vendorExtensions.x-objc-operationId}}{{vendorExtensions.x-objc-operationId}}{{/vendorExtensions.x-objc-operationId}}{{^vendorExtensions.x-objc-operationId}}{{nickname}}{{#hasParams}}With{{vendorExtensions.firstParamAltName}}{{/hasParams}}{{^hasParams}}WithCompletionHandler: {{/hasParams}}{{/vendorExtensions.x-objc-operationId}}{{#allParams}}{{#secondaryParam}}
+    {{paramName}}{{/secondaryParam}}: ({{{dataType}}}) {{paramName}}{{/allParams}}
+        {{#hasParams}}completionHandler: {{/hasParams}}(void (^)({{#returnBaseType}}{{{returnType}}} output, {{/returnBaseType}}NSError* error)) handler;
+```
+
+{{{summary}}}{{#notes}}
+
+{{{notes}}}{{/notes}}
+
+### Example 
+```objc
+{{#hasAuthMethods}}
+{{classPrefix}}Configuration *apiConfig = [{{classPrefix}}Configuration sharedConfig];
+{{#authMethods}}{{#isBasic}}// Configure HTTP basic authorization (authentication scheme: {{{name}}})
+[apiConfig setUsername:@"YOUR_USERNAME"];
+[apiConfig setPassword:@"YOUR_PASSWORD"];
+{{/isBasic}}{{#isApiKey}}
+// Configure API key authorization: (authentication scheme: {{{name}}})
+[apiConfig setApiKey:@"YOUR_API_KEY" forApiKeyIdentifier:@"{{{keyParamName}}}"];
+// Uncomment below to setup prefix (e.g. BEARER) for API key, if needed
+//[apiConfig setApiKeyPrefix:@"BEARER" forApiKeyIdentifier:@"{{{keyParamName}}}"];
+{{/isApiKey}}{{#isOAuth}}
+// Configure OAuth2 access token for authorization: (authentication scheme: {{{name}}})
+[apiConfig setAccessToken:@"YOUR_ACCESS_TOKEN"];
+{{/isOAuth}}{{/authMethods}}
+{{/hasAuthMethods}}
+
+{{#allParams}}{{{dataType}}} {{paramName}} = {{{example}}}; // {{{description}}}{{^required}} (optional){{/required}}{{#defaultValue}} (default to {{{.}}}){{/defaultValue}}
+{{/allParams}}
+
+@try
+{ 
+    {{classname}} *apiInstance = [[{{classname}} alloc] init];
+
+{{#summary}}    // {{{.}}}
+{{/summary}}    [apiInstance {{#vendorExtensions.x-objc-operationId}}{{vendorExtensions.x-objc-operationId}}{{/vendorExtensions.x-objc-operationId}}{{^vendorExtensions.x-objc-operationId}}{{nickname}}{{#hasParams}}With{{vendorExtensions.firstParamAltName}}{{/hasParams}}{{^hasParams}}WithCompletionHandler: {{/hasParams}}{{/vendorExtensions.x-objc-operationId}}{{#allParams}}{{#secondaryParam}}
+                  {{paramName}}{{/secondaryParam}}:{{paramName}}{{/allParams}}
+              {{#hasParams}}completionHandler: {{/hasParams}}^({{#returnBaseType}}{{{returnType}}} output, {{/returnBaseType}}NSError* error) {
+{{#returnType}}
+                            if (output) {
+                                NSLog(@"%@", output);
+                            }
+{{/returnType}}
+                            if (error) {
+                                NSLog(@"Error: %@", error);
+                            }
+                        }];
+}
+@catch (NSException *exception)
+{
+    NSLog(@"Exception when calling {{classname}}->{{operationId}}: %@ ", exception.name);
+    NSLog(@"Reason: %@ ", exception.reason);
+}
+```
+
+### 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/objc/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}}

samples/client/petstore/objc/README.md

@@ -1,20 +1,200 @@
 # SwaggerClient
 
+This is a sample server Petstore server.  You can find out more about Swagger at <a href=\"http://swagger.io\">http://swagger.io</a> or on irc.freenode.net, #swagger.  For this sample, you can use the api key \"special-key\" to test the authorization filters
+
+This ObjC package is automatically generated by the [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) project:
+
+- API version: 1.0.0
+- Package version: 
+- Build date: 2016-04-05T23:29:02.396+08:00
+- Build package: class io.swagger.codegen.languages.ObjcClientCodegen
+
 ## Requirements
 
-The API client library requires ARC (Automatic Reference Counting) to be enabled in your Xcode project.
+The SDK requires [**ARC (Automatic Reference Counting)**](http://stackoverflow.com/questions/7778356/how-to-enable-disable-automatic-reference-counting) to be enabled in the Xcode project.
 
-## Installation
+## Installation & Usage
+### Install from Github using [CocoaPods](https://cocoapods.org/)
 
-To install it, put the API client library in your project and then simply add the following line to your Podfile:
+Add the following to the Podfile:
 
 ```ruby
-pod "SwaggerClient", :path => "/path/to/lib"
+pod 'SwaggerClient', :git => 'https://github.com/YOUR_GIT_USR_ID/YOUR_GIT_REPO_ID.git'
+```
+
+To specify a particular branch, append `, :branch => 'branch-name-here'`
+
+To specify a particular commit, append `, :commit => '11aa22'`
+
+### Install from local path using [CocoaPods](https://cocoapods.org/)
+
+Put the SDK under your project folder (e.g. /path/to/objc_project/Vendor/SwaggerClient) and then add the following to the Podfile:
+
+```ruby
+pod 'SwaggerClient', :path => 'Vendor/SwaggerClient'
+```
+
+### Usage
+
+Import the following:
+```objc
+#import <SwaggerClient/SWGApiClient.h>
+#import <SwaggerClient/SWGConfiguration.h>
+// load models
+#import <SwaggerClient/SWG200Response.h>
+#import <SwaggerClient/SWGAnimal.h>
+#import <SwaggerClient/SWGCat.h>
+#import <SwaggerClient/SWGCategory.h>
+#import <SwaggerClient/SWGDog.h>
+#import <SwaggerClient/SWGInlineResponse200.h>
+#import <SwaggerClient/SWGName.h>
+#import <SwaggerClient/SWGOrder.h>
+#import <SwaggerClient/SWGPet.h>
+#import <SwaggerClient/SWGReturn.h>
+#import <SwaggerClient/SWGSpecialModelName_.h>
+#import <SwaggerClient/SWGTag.h>
+#import <SwaggerClient/SWGUser.h>
+// load API classes for accessing endpoints
+#import <SwaggerClient/SWGPetApi.h>
+#import <SwaggerClient/SWGStoreApi.h>
+#import <SwaggerClient/SWGUserApi.h>
+
 ```
 
 ## Recommendation
 
-It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issue.
+It's recommended to create an instance of ApiClient per thread in a multi-threaded environment to avoid any potential issue.
+
+## Getting Started
+
+Please follow the [installation procedure](#installation--usage) and then run the following:
+
+```objc
+
+SWGConfiguration *apiConfig = [SWGConfiguration sharedConfig];
+
+// Configure OAuth2 access token for authorization: (authentication scheme: petstore_auth)
+[apiConfig setAccessToken:@"YOUR_ACCESS_TOKEN"];
+
+
+SWGPet* *body = [[SWGPet alloc] init]; // Pet object that needs to be added to the store (optional)
+
+@try
+{
+    SWGPetApi *apiInstance = [[SWGPetApi alloc] init];
+
+    // Add a new pet to the store
+    [apiInstance addPetWithBody:body
+              completionHandler: ^(NSError* error)) {
+                            if (error) {
+                                NSLog(@"Error: %@", error);
+                            }
+                        }];
+}
+@catch (NSException *exception)
+{
+    NSLog(@"Exception when calling SWGPetApi->addPet: %@ ", exception.name);
+    NSLog(@"Reason: %@ ", exception.reason);
+}
+
+```
+
+## Documentation for API Endpoints
+
+All URIs are relative to *http://petstore.swagger.io/v2*
+
+Class | Method | HTTP request | Description
+------------ | ------------- | ------------- | -------------
+*SWGPetApi* | [**addPet**](docs/SWGPetApi.md#addpet) | **POST** /pet | Add a new pet to the store
+*SWGPetApi* | [**addPetUsingByteArray**](docs/SWGPetApi.md#addpetusingbytearray) | **POST** /pet?testing_byte_array=true | Fake endpoint to test byte array in body parameter for adding a new pet to the store
+*SWGPetApi* | [**deletePet**](docs/SWGPetApi.md#deletepet) | **DELETE** /pet/{petId} | Deletes a pet
+*SWGPetApi* | [**findPetsByStatus**](docs/SWGPetApi.md#findpetsbystatus) | **GET** /pet/findByStatus | Finds Pets by status
+*SWGPetApi* | [**findPetsByTags**](docs/SWGPetApi.md#findpetsbytags) | **GET** /pet/findByTags | Finds Pets by tags
+*SWGPetApi* | [**getPetById**](docs/SWGPetApi.md#getpetbyid) | **GET** /pet/{petId} | Find pet by ID
+*SWGPetApi* | [**getPetByIdInObject**](docs/SWGPetApi.md#getpetbyidinobject) | **GET** /pet/{petId}?response=inline_arbitrary_object | Fake endpoint to test inline arbitrary object return by &#39;Find pet by ID&#39;
+*SWGPetApi* | [**petPetIdtestingByteArraytrueGet**](docs/SWGPetApi.md#petpetidtestingbytearraytrueget) | **GET** /pet/{petId}?testing_byte_array=true | Fake endpoint to test byte array return by &#39;Find pet by ID&#39;
+*SWGPetApi* | [**updatePet**](docs/SWGPetApi.md#updatepet) | **PUT** /pet | Update an existing pet
+*SWGPetApi* | [**updatePetWithForm**](docs/SWGPetApi.md#updatepetwithform) | **POST** /pet/{petId} | Updates a pet in the store with form data
+*SWGPetApi* | [**uploadFile**](docs/SWGPetApi.md#uploadfile) | **POST** /pet/{petId}/uploadImage | uploads an image
+*SWGStoreApi* | [**deleteOrder**](docs/SWGStoreApi.md#deleteorder) | **DELETE** /store/order/{orderId} | Delete purchase order by ID
+*SWGStoreApi* | [**findOrdersByStatus**](docs/SWGStoreApi.md#findordersbystatus) | **GET** /store/findByStatus | Finds orders by status
+*SWGStoreApi* | [**getInventory**](docs/SWGStoreApi.md#getinventory) | **GET** /store/inventory | Returns pet inventories by status
+*SWGStoreApi* | [**getInventoryInObject**](docs/SWGStoreApi.md#getinventoryinobject) | **GET** /store/inventory?response=arbitrary_object | Fake endpoint to test arbitrary object return by &#39;Get inventory&#39;
+*SWGStoreApi* | [**getOrderById**](docs/SWGStoreApi.md#getorderbyid) | **GET** /store/order/{orderId} | Find purchase order by ID
+*SWGStoreApi* | [**placeOrder**](docs/SWGStoreApi.md#placeorder) | **POST** /store/order | Place an order for a pet
+*SWGUserApi* | [**createUser**](docs/SWGUserApi.md#createuser) | **POST** /user | Create user
+*SWGUserApi* | [**createUsersWithArrayInput**](docs/SWGUserApi.md#createuserswitharrayinput) | **POST** /user/createWithArray | Creates list of users with given input array
+*SWGUserApi* | [**createUsersWithListInput**](docs/SWGUserApi.md#createuserswithlistinput) | **POST** /user/createWithList | Creates list of users with given input array
+*SWGUserApi* | [**deleteUser**](docs/SWGUserApi.md#deleteuser) | **DELETE** /user/{username} | Delete user
+*SWGUserApi* | [**getUserByName**](docs/SWGUserApi.md#getuserbyname) | **GET** /user/{username} | Get user by user name
+*SWGUserApi* | [**loginUser**](docs/SWGUserApi.md#loginuser) | **GET** /user/login | Logs user into the system
+*SWGUserApi* | [**logoutUser**](docs/SWGUserApi.md#logoutuser) | **GET** /user/logout | Logs out current logged in user session
+*SWGUserApi* | [**updateUser**](docs/SWGUserApi.md#updateuser) | **PUT** /user/{username} | Updated user
+
+
+## Documentation For Models
+
+ - [SWG200Response](docs/SWG200Response.md)
+ - [SWGAnimal](docs/SWGAnimal.md)
+ - [SWGCat](docs/SWGCat.md)
+ - [SWGCategory](docs/SWGCategory.md)
+ - [SWGDog](docs/SWGDog.md)
+ - [SWGInlineResponse200](docs/SWGInlineResponse200.md)
+ - [SWGName](docs/SWGName.md)
+ - [SWGOrder](docs/SWGOrder.md)
+ - [SWGPet](docs/SWGPet.md)
+ - [SWGReturn](docs/SWGReturn.md)
+ - [SWGSpecialModelName_](docs/SWGSpecialModelName_.md)
+ - [SWGTag](docs/SWGTag.md)
+ - [SWGUser](docs/SWGUser.md)
+
+
+## Documentation For Authorization
+
+
+## test_api_key_header
+
+- **Type**: API key
+- **API key parameter name**: test_api_key_header
+- **Location**: HTTP header
+
+## api_key
+
+- **Type**: API key
+- **API key parameter name**: api_key
+- **Location**: HTTP header
+
+## test_http_basic
+
+- **Type**: HTTP basic authentication
+
+## test_api_client_secret
+
+- **Type**: API key
+- **API key parameter name**: x-test_api_client_secret
+- **Location**: HTTP header
+
+## test_api_client_id
+
+- **Type**: API key
+- **API key parameter name**: x-test_api_client_id
+- **Location**: HTTP header
+
+## test_api_key_query
+
+- **Type**: API key
+- **API key parameter name**: test_api_key_query
+- **Location**: URL query string
+
+## petstore_auth
+
+- **Type**: OAuth
+- **Flow**: implicit
+- **Authorizatoin URL**: http://petstore.swagger.io/api/oauth/dialog
+- **Scopes**: 
+ - **write:pets**: modify pets in your account
+ - **read:pets**: read your pets
+
 
 ## Author
 

samples/client/petstore/objc/SwaggerClient/SWGApiClient.h

@@ -13,7 +13,10 @@
  */
 
 #import "SWG200Response.h"
+#import "SWGAnimal.h"
+#import "SWGCat.h"
 #import "SWGCategory.h"
+#import "SWGDog.h"
 #import "SWGInlineResponse200.h"
 #import "SWGName.h"
 #import "SWGOrder.h"
@@ -81,7 +84,7 @@ extern NSString *const SWGResponseObjectErrorKey;
 +(bool) getOfflineState;
 
 /**
- * Sets the client reachability, this may be override by the reachability manager if reachability changes
+ * Sets the client reachability, this may be overridden by the reachability manager if reachability changes
  *
  * @param The client reachability.
  */

samples/client/petstore/objc/SwaggerClient/SWGApiClient.m

@@ -716,11 +716,11 @@ static void (^reachabilityChangeBlock)(int);
     for (NSString *auth in authSettings) {
         NSDictionary *authSetting = [[config authSettings] objectForKey:auth];
 
-        if (authSetting) {
+        if (authSetting) { // auth setting is set only if the key is non-empty
-            if ([authSetting[@"in"] isEqualToString:@"header"]) {
+            if ([authSetting[@"in"] isEqualToString:@"header"] && [authSetting[@"key"] length] != 0) {
                 [headersWithAuth setObject:authSetting[@"value"] forKey:authSetting[@"key"]];
             }
-            else if ([authSetting[@"in"] isEqualToString:@"query"]) {
+            else if ([authSetting[@"in"] isEqualToString:@"query"] && [authSetting[@"key"] length] != 0) {
                 [querysWithAuth setObject:authSetting[@"value"] forKey:authSetting[@"key"]];
             }
         }

samples/client/petstore/objc/SwaggerClient/SWGConfiguration.h

@@ -46,6 +46,11 @@
  */
 @property (nonatomic) NSString *password;
 
+/**
+ * Access token for OAuth
+ */
+@property (nonatomic) NSString *accessToken;
+
 /**
  * Temp folder for file download
  */
@@ -132,6 +137,11 @@
  */
 - (NSString *) getBasicAuthToken;
 
+/**
+ * Gets OAuth access token
+ */
+- (NSString *) getAccessToken;
+
 /**
  * Gets Authentication Setings
  */

samples/client/petstore/objc/SwaggerClient/SWGConfiguration.m

@@ -29,6 +29,7 @@
         self.host = @"http://petstore.swagger.io/v2";
         self.username = @"";
         self.password = @"";
+        self.accessToken= @"";
         self.tempFolderPath = nil;
         self.debug = NO;
         self.verifySSL = YES;
@@ -42,18 +43,23 @@
 #pragma mark - Instance Methods
 
 - (NSString *) getApiKeyWithPrefix:(NSString *)key {
-    if ([self.apiKeyPrefix objectForKey:key] && [self.apiKey objectForKey:key]) {
+    if ([self.apiKeyPrefix objectForKey:key] && [self.apiKey objectForKey:key] != (id)[NSNull null] && [[self.apiKey objectForKey:key] length] != 0) { // both api key prefix and api key are set 
         return [NSString stringWithFormat:@"%@ %@", [self.apiKeyPrefix objectForKey:key], [self.apiKey objectForKey:key]];
     }
-    else if ([self.apiKey objectForKey:key]) {
+    else if ([self.apiKey objectForKey:key] != (id)[NSNull null] && [[self.apiKey objectForKey:key] length] != 0) { // only api key, no api key prefix
         return [NSString stringWithFormat:@"%@", [self.apiKey objectForKey:key]];
     }
-    else {
+    else { // return empty string if nothing is set
         return @"";
     }
 }
 
 - (NSString *) getBasicAuthToken {
+    // return empty string if username and password are empty
+    if (self.username.length == 0 && self.password.length == 0){
+        return  @"";
+    }
+
     NSString *basicAuthCredentials = [NSString stringWithFormat:@"%@:%@", self.username, self.password];
     NSData *data = [basicAuthCredentials dataUsingEncoding:NSUTF8StringEncoding];
     basicAuthCredentials = [NSString stringWithFormat:@"Basic %@", [data base64EncodedStringWithOptions:0]];
@@ -61,6 +67,15 @@
     return basicAuthCredentials;
 }
 
+- (NSString *) getAccessToken {
+    if (self.accessToken.length == 0) { // token not set, return empty string
+        return @"";
+    }
+    else {
+        return [NSString stringWithFormat:@"BEARER %@", self.accessToken];
+    }
+}
+
 #pragma mark - Setter Methods
 
 - (void) setApiKey:(NSString *)apiKey forApiKeyIdentifier:(NSString *)identifier {
@@ -149,6 +164,13 @@
                        @"key": @"test_api_key_query",
                        @"value": [self getApiKeyWithPrefix:@"test_api_key_query"]
                    },
+               @"petstore_auth":
+                   @{
+                       @"type": @"oauth",
+                       @"in": @"header",
+                       @"key": @"Authorization",
+                       @"value": [self getAccessToken]
+                   },
                };
 }