AccountApi#authenticate method throws too-ambiguous Exception

[freen]

Throwing an exception using the generic "Exception" class is not best practice. It's counter intuitive in the following way:

When implementing the API, we have to wrap this in a try/catch block like so:

// Attempt Wordnik API authentication.
try {
    $authResponse = $this->wordnik->authenticate($username, $token->getPassword());
} catch(\Exception $errorResponse) {
    $errorMessage = $errorResponse->getMessage();
    // ...
}

However by catching "Exception", we may end up catching Exceptions we didn't intend to catch, preventing other Exceptions from coming to light, and causing new problems in our catch clause.

For example: What if $token->getPassword() produces an exception? This will also be caught by my try/catch block, however my catch block was written to anticipate the specific use of the Exception class coming from ApiAccount#authenticate, and now an Exception might occur in my catch block. I just experienced this exact issue.

The solution to this problem is to create custom, Swagger-specific Exception classes, i.e. in this case SwaggerApiAuthenticationException. Then my try/catch block could target this specific Exception, and I wouldn't, as they say, catch 'em all.

I know that the API is Swagger-generated so I won't fork the repository or submit a patch. However it would be ideal if Swagger was able to generate PHP API wrappers which defined and implemented custom exceptions.

EDIT:

This problem also effects timeout issues. When there's a timeout on the request, an Exception gets thrown, but aside from inspecting the Exception's error message, I have no way of knowing that the user didn't supply an incorrect password. This is because the Exceptions all have the same class, and none of them have error codes, so there's no real way to distinguish what the problem was.

[mrjf]

Agreed (and very nicely explained, I would add!). Making a TODO for myself to implement this.