do you have an example of good API errors (in some lib/tech)?

I think so, yes. I have a ruby background and one of the web frameworks I used most of the time was grape (https://github.com/ruby-grape/grape). they have a way to validate/coerce params (https://github.com/ruby-grape/grape#parameter-validation-and-coercion), relying both on a library called virtus (https://github.com/solnic/virtus) and on a set of their own validations.

if I recall correctly, the messages coming from virtus were somewhat like the ones coming from schema. helpful and understandable, just not prepared for customer-facing use cases.

I think they do the error formatting in a rack middleware (quite similar concept to a ring middleware)

if compojure api exposed something like this, I imagine that would be an interesting strategy as well?

the error messages are defined here: https://github.com/ruby-grape/grape/blob/master/lib/grape/locale/en.yml

there are more things there than the validation error messages, but I think you can get an idea by looking at the existing validations and looking for the corresponding error messages.

maybe this is already too detailed, but showing the messages without giving some context seemed innapropriate

yeah, that look great. The error formatting is done in ring-swagger: https://github.com/metosin/ring-swagger/blob/master/src/ring/swagger/middleware.clj#L43-L74

so, you can pass any custom function to render the exception messages instead of the default one. If you come up with a better formatter than the custom, let’s pull it in.

great! 🙂 I will take a look and I hope I can get back to you with a proposal.

hey guys

I have a documented route, but I would not like it to validate the schema

can’t find an easy way to do it

do you just have one route where you dont want validation? do you still want to destructure the parameters?

setting :coercion nil disables the coercion. can be se to api, context or endpoints.

BUT still the parameter destructuring is done, do if you ask for :query-params [x :- s/Int, y :- s/Int], the keys still have to be present.

to do just documentation, you can use :swagger -destructuring, described here: https://github.com/metosin/compojure-api/wiki/Swagger-integration#non-documented-routes

when I add :coercion nil

I get an exception

I’ like to prevent schema validation for specific routs

but if I have to, we can disable it everywhere

because we already have a validation layer, we’re using compojure-api just for docs

what version are you using?

1.1.0

will bump it

ok, the nil needs the latest. just added it ~last week 😉

yes, running ok! 🙂

thanks

I’ve seen an issue about spec

any news on that?

you can follow that on the ring-swagger (https://github.com/metosin/ring-swagger/issues/95). Miikka just pushed a initial prototype. Looking forward to that. Still, spec doesn’t really support coercions in the way http apis need. Will poke Alex, if we could have that.

👍

Hi! Is there an example somewhere how to define an endpoint (PUT or POST) in compojure-api that accepts binary data? I would like to read directly from the :body stream of the ring request.

you can use normal Compojure way to access the request:

(POST “/bin” request
  (dosomethingwith (:body request))

For files, there is also the multipart-params handling, either via a temp file or a inputstream, sample here: https://github.com/metosin/compojure-api/blob/master/examples/thingie/src/examples/thingie.clj#L189-L193

Thanks! I'm not sure yet if I want the multipart handling. If I go the first way you showed, how can I generate the right Swagger definition for this?

what kind of definition should there be?

a map-like schema of the body perhaps?

or are you streaming files?

I'm not sure. 🙂 Sorry, I'm still pretty new to Swagger and Schema. Is there a way in Swagger to say "accept any binary data".

I don’t think there is.

Swagger is originally made for statically typed languages & JSON-type apis.

True. It's not a common case, I guess. I'll just use the standard Compojure way for now.

Thanks for the help!

glad to help