search

metosin / compojure-api

Sweet web apis with Compojure & Swagger
http://metosin.github.io/compojure-api/doc/
Eclipse Public License 1.0
1.12k stars 149 forks source link

Description for path-params and query-params #34

Closed sebastiansen closed 10 years ago

sebastiansen commented 10 years ago

I haven't been able to add a description to a path param, I tried the following but didn't work:

(GET* "/:id" []
   :path-params [id :- (field String {:description "unique identifier"})]
   ...)
ikitommi commented 10 years ago

Hi.

thanks for reporting, found a reason for this (schema meta-data is lost due to evaluation of schemas during macro expansion), I think I know how to fix this, try to fix it before the starting holidays next week.

psarando commented 10 years ago

Any update on this issue? I also would like to be able to add descriptions to query and path-params. This still does not appear to work in compojure-api 0.14.0, or is there an alternate way to attach descriptions to these params?

ikitommi commented 10 years ago

Hi. Sorry for the lag, we're on summer vacation right now. Will go thru the bugs when back with computer (in few weeks). This should be quite straightforward to fix, also PRs welcome.

Any update on this issue? I also would like to be able to add descriptions to query and path-params. This still does not appear to work in compojure-api 0.14.0, or is there an alternate way to attach descriptions to these params?

— Reply to this email directly or view it on GitHub https://github.com/metosin/compojure-api/issues/34#issuecomment-49439824.

arnab commented 10 years ago

I tried to add description to query params. The param page shows up on the swagger UI, but the description ABC does not.

(s/defschema PaginationParams {(s/optional-key :page)
                                 (ring-s/field Long {:description "ABC"})})

What am I missing?

ikitommi commented 10 years ago

Back. Juho, you had a patch for this coming up?

Deraen commented 10 years ago

Okay,

I think I have this mostly working now: da3c45ff38767d243f13812b61985b7288eb3f35. This required quit large refactoring of ring-swagger code: https://github.com/metosin/ring-swagger/compare/paramater-metadata?expand=1

Thingie example should have examples of working ways to describe Schema elements.

I think following should also work, but are currently broken:

:return (describe Model "The return schema")
:body [body (describe Body "The input schema")]
Deraen commented 10 years ago

This should work now with the 0.15.0 release.

arnab commented 10 years ago

Thanks @Deraen - I can confirm it's working (I can successfully add descriptions to my query params).