search

metosin / reitit

A fast data-driven routing library for Clojure/Script
https://cljdoc.org/d/metosin/reitit/
Eclipse Public License 1.0
1.43k stars 256 forks source link

Unclear where swagger tags should be placed #375

Open Deraen opened 4 years ago

Deraen commented 4 years ago

Swagger feature docstring (and spec?) places tags on route-data root:

https://github.com/metosin/reitit/blob/master/modules/reitit-swagger/src/reitit/swagger.cljc#L55

Examples place tags key under swagger:

https://github.com/metosin/reitit/blob/master/examples/ring-swagger/src/example/server.clj#L30

Both seem to generate proper swagger.json, but first one fails spec validation. Why? Spec seems to list tags as top-level key.

ikitommi commented 4 years ago

You need to mount swagger-feature as a middleware|interceptor, which adds the valid keys to the route data for the routes swagger-feature effects

ikitommi commented 4 years ago

e.g. all specs from mw/int :spec key accumulate to the route spec. Would be great to see the accumulated spec per endpoint.

ikitommi commented 4 years ago

I think the right solution is to remove the top-level :tags completely and use path [:swagger :tags] instead.

ikitommi commented 4 years ago

oh, it a breaking. but the :tags has never been part of the route spec, so this is still a bug fix. need to push a minor out with this.

On Thu, Jun 25, 2020 at 12:36 PM Tommi Jalkanen notifications@github.com wrote:

I know it would be a breaking change but what about this line: https://github.com/metosin/reitit/blob/9ca88d7165c97ec1c5bb87dd5a217bc58ad1de50/modules/reitit-swagger/src/reitit/swagger.cljc#L96

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/metosin/reitit/issues/375#issuecomment-649425705, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAEKR3DY5AUB2OBBWQFEGEDRYMLDJANCNFSM4LF2IESQ .