adding docs and examples for headers

Author: cesine

README.md

@@ -224,6 +224,46 @@ You can add it to the swagger-client like such:
 client.clientAuthorizations.add('my-auth', new CustomRequestSigner());
 ```
 
+### Setting headers
+
+Headers are a type of `parameter`, and can be passed with the other parameters. For example, if you supported translated pet details via the `Accept-Language` header:
+
+```js
+"parameters": [
+  {
+    "name": "petId",
+    "description": "ID of pet that needs to be fetched",
+    "required": true,
+    "type": "integer",
+    "format": "int64",
+    "paramType": "path",
+    "minimum": "1.0",
+    "defaultValue": 3,
+    "maximum": "100000.0"
+  },
+  "LanguageHeader": {
+    "name": "Accept-Language",
+    "in": "header",
+    "description": "Specify the user's language",
+    "required": false,
+    "type": "string"
+  }
+...
+```
+
+Then you would pass the header value via the parameters ([header parameters are case-insenstive](https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2)):
+
+```js
+
+client.pet.getPetById({
+  petId: 7,
+  'accept-language': 'fr'
+}, function(pet){
+  console.log('pet', pet);
+});
+
+```
+
 ### Using your own HTTP client
 
 Don't like [superagent](https://github.com/visionmedia/superagent)? Despise [JQuery](https://github.com/jquery/jquery)?  Well, you're in luck.  You can plug your own HTTP library easily:

test/client.js

@@ -703,7 +703,7 @@ describe('SwaggerClient', function () {
             parameters: [
               {
                 in: 'header',
-                name: 'username',
+                name: 'Accept-Language',
                 type: 'string'
               }
             ],
@@ -735,7 +735,7 @@ describe('SwaggerClient', function () {
            **/
 
           // ensure the headers are present
-          expect(requestObj.headers.username).toBe('bob');
+          expect(requestObj.headers['Accept-Language']).toBe('fr');
 
           // rewrite this request to something that'll work locally
           requestObj.method = 'GET';
@@ -751,7 +751,7 @@ describe('SwaggerClient', function () {
       usePromise: true,
       requestInterceptor: interceptor.requestInterceptor
     }).then(function(client) {
-      client.nada.addFoo({username: 'bob'}).then(function (){
+      client.nada.addFoo({'accept-LANGUAGE': 'fr'}).then(function (){
         done();
       });
     }).catch(function(exception) {

test/headers.js

@@ -29,19 +29,19 @@ describe('header extraction', function () {
     var parameters = [
       {
         in: 'header',
-        name: 'myHeader',
+        name: 'Request-ID',
         type: 'string'
       }
     ];
     var op = new Operation({}, 'http', 'test', 'get', '/path', { parameters: parameters });
     var args = {
-      MyHeAdeR: 'nick'
+      'request-Id': '12ab34ef'
     };
     var url = op.urlify(args);
     var headers = op.getHeaderParams(args);
 
     expect(url).toBe('http://localhost/path');
-    expect(headers.myHeader).toBe('nick');
+    expect(headers['Request-ID']).toBe('12ab34ef');
   });
 
   it('should not URL encode header string values', function () {

test/spec/v2/spec3.json

@@ -25,6 +25,9 @@
             "description": "Status values that need to be considered for filter",
             "required": false,
             "type": "string"
+          },
+          {
+            "$ref": "#/parameters/LanguageHeader"
           }
         ],
         "responses": {
@@ -40,5 +43,14 @@
         }
       }
     }
+  },
+  "parameters": {
+    "LanguageHeader": {
+      "name": "Accept-Language",
+      "in": "header",
+      "description": "Specify the user's language",
+      "required": false,
+      "type": "string"
+    }
   }
-}
+}