Fix #2120, #2157 - Update Swift API method generation for ease of use

[hideya]

Fix #2120, #2157 -- Note this is a Breaking Change.

The following illustrates the differences in the usage of generated SDK:

Before:

        PetstoreClientAPI.PetAPI.getPetById(petId: 1000).execute { response, error -> Void in
                let pet = response?.body

After:

        PetAPI.getPetById(petId: 1000) { pet, error -> Void in

PromiseKit ready version of simplified methods are also generated:

Before:

        PetstoreClientAPI.PetAPI.getPetById(petId: 1000).execute().then { response -> Void in
                let pet = response.body

After:

        PetAPI.getPetById(petId: 1000).then { pet -> Void in

The {{projectName}}API namespace for API classes (PetstoreClientAPI above) now became optional and can be turned on via a CLI option: -D swiftUseApiNamespace=true

In order to allow developers to access the response object when needed, the old methods still exist with WithRequestBuilder added to the end of the method name:

Before:

public class func getPetById(petId petId: Int) -> RequestBuilder<Pet> {

After:

public class func getPetByIdWithRequestBuilder(petId petId: Int) -> RequestBuilder<Pet> {

I initially thought to provide an improved abstraction over these WithRequestBuilder methods (to make them look closer to C#'s WithHttpInfo methods), but it will involve more lines to add (esp. to provide PromiseKit ready version). I thought it better be done in a separate PR.

[wing328]

@hideya thanks for the PR. The description is very clear and the changes look good to me.

cc @jaz-ah @Edubits to see if they've any feedback.

[hideya]

@wing328 I've updated this PR and included fix for #2157 (I've also updated the description above accordingly). Would you please review the changes once again?

[wing328]

@hideya looks good to me and that's how I would have done it.