Error handling and response schemas

[allan-stewart]

I'm trying to get started building Apigee-127 proxies, but I'm having trouble figuring out how to map to response types defined by swagger, especially for error cases.

For example, take the "hello world" template code that is created when you do a127 project create <name>, and make a single change: make the ?name= query string parameter required.

If you do provide a valid name, the example project doesn't return a JSON structure I'd expect based on the HelloWorldResponse in the swagger.yaml. We just get a string saying "Hello, John" instead of {"message": "Hello, John"}. That can be easily fixed by updating the controller code, though it seems I have to personally ensure that my response body matches the swagger definition.

But if you don't provide a name, the swagger middleware throws a validation error (we made it a required value) and the controller isn't called. The end result does not match the ErrorResponse type defined in the swagger.yaml.

How is this meant to be handled? Is there something built into Apigee-127 for helping developers map to the swagger-defined responses?

I read this StackOverflow post and issue #37 but they only talked about the HTTP status code, not the response body.

I know I can create a middleware error handler in the app.js file (something like app.use(function(err, req, res, next) {...}); and I see that I can get info from the req.swagger object... But it seems like there's still a lot of work I'd have to do to determine how to map the error to the appropriate JSON body. And it could get much more complicated as I add additional routes since there is only one error handler.

It would be nice if the tooling helped out here somehow. Maybe transform errors into the default response types? Or allow controllers to define an error handler (or validationErrorHandler) which the swagger middleware could call? Or am I just missing something?

[whitlockjc]

I understand what you're saying but I'm not sure how swagger-tools could do more right now. The middleware way to do it would be to register/use an error handler middleware and compose your response there. That would work in any server environment and would work right now. I realize it's more work on your part but it would work and you have complete control.

On the other hand, I can understand you expecting/wanting swagger-tools to do this, or at least help. The problem is I haven't come up with a way that doesn't seem like a hack or require boilerplate on your part in your Swagger document. Until we can come up with an approach that is neither a hack or intrusive, I don't know what else I can do.

I'm open to suggestions.

[theganyo]

No, you're not missing anything, @allan-stewart. I agree that something should be done about this... and I believe swagger-tools would be the place for it. But it will require a bit of thought to get it right (as @whitlockjc said). Thanks for filing this issue!

[whitlockjc]

Agreed. Let me put more thought into this and as I mentioned earlier, I'm open to suggestions.

[allan-stewart]

Sure thing. My team will be playing around with it for a while, so if we come up with any good ideas on how to handle this, we'll pass them along too. Otherwise, we're interested to see how this project evolves. 👍

[whitlockjc]

Have you given this any more thought, assuming you're still using swagger-tools? The only thing I can think of would be very brittle and it would require you to set res.statusCode prior to flagging the error. Either that or I expose an API to get the response for a given status code and then use that to help you out.