fixed documentation (WIP) (Azure#1332)

* Update creating-swagger.md

* Update creating-swagger.md

documentation/creating-swagger.md

@@ -269,7 +269,7 @@ Query parameters are appended to the request URI. They can be specified as requi
 ```
 The user doesn't need to know where the parameter is placed. Doc comments surface the required/optional distinction.
 
-####Body Parameters<a name="BodyParameters"></a>
+#### Body Parameters<a name="BodyParameters"></a>
 Body parameters include schema for the payload. In this example, the schema element is a `$ref` to the type details 
 in the `#/definitions` section of the spec. More on the `#/definitions` later.
 ```json5
@@ -291,7 +291,24 @@ in the `#/definitions` section of the spec. More on the `#/definitions` later.
 ```
 
 #### Header Parameters<a name="HeaderParameters"></a>
->TODO: Header parameters
+Header parameters are sent as part of the HTTP request header.
+In general, reserved headers (`Content-Length`, `Content-Type`, ...) should not be documented since their values are derivable (e.g. from the request body) and not really part of the protocol specified by the OpenAPI definition.
+Rather, they are part of the REST standard that the protocol is supposed to adhere to anyway.
+
+However, there are rare scenarios for making the `Content-Type` customizable as part of a request, e.g. in case of a binary/stream request body.
+The media type of binary request bodies is not reliably derivable: Maybe the service endpoint accepts PNG, JPEG or BMP images, which is expressed in OpenAPI using
+``` yaml
+consumes:
+  - image/png
+  - image/jpeg
+  - image/bmp
+```
+and give the request body type `file`.
+Now, when a request is made, the protocol has to somehow communicate to the server which of the media types the body has.
+Since there is a range of possibilities (and it's certainly not a protocol's job to parse and classify binary data), we suggest adding a `Content-Type` header parameter to the operation's definition.
+Unless one provides an `enum` restriction for that parameter, [AutoRest](https://github.com/Azure/autorest) will automatically make the parameter an enum with values drawn from the `consumes` declaration.
+This allows for deduplication and hence prevents potential bugs.
+More information on how [AutoRest](https://github.com/Azure/autorest) treats a `Content-Type` header parameter can be found [here](https://github.com/Azure/autorest/tree/master/Samples/test/stream-with-content-type).
 
 #### FormData Parameters<a name="FormDataParameters"></a>
 >Note: FormData parameters are not currently supported by AutoRest.
@@ -784,7 +801,7 @@ terminal states`Succeeded|Failed|Canceled`.
 }
 ```
 
-##Global parameters<a name="globalParam"></a>
+## Global parameters<a name="globalParam"></a>
 Swagger allows for parameters to be defined separately from the operation where they are used. By convention, AutoRest 
 treats global parameter definitions as Client properties. For example, almost all Azure Resource Manager APIs require 
 `subscriptionId` and `api-version`. These are defined as global parameters and become properties of the client.
@@ -836,4 +853,4 @@ If an operation requires that a parameter is exposed as a method parameter, it i
 
 TODO: naming standards for operations Create, CreateOrUpdate, Update (respect etag), Get, List, Delete, Patch
 TODO: patch => no validate
-[Swagger-spec2.0]:https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
+[Swagger-spec2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)