ring-swagger & compojure-api
vuuvi 2018-08-09T15:52:11.000571Z

hi all! are there any guides on how to use ring-swagger for an already existing API?

vuuvi 2018-08-09T15:53:58.000513Z

I’ve gotten as far as understanding that you need to use schema to mark up the API endpoints and ring-swagger will generate an index.html file to display the endpoints from the markup

vuuvi 2018-08-09T15:54:23.000289Z

I just want to make sure I’m not missing anything as I start to use ring-swagger day to day

ikitommi 2018-08-09T15:55:11.000135Z

are you using schema for coercion already?

ikitommi 2018-08-09T15:57:51.000063Z


(GET "/path/:x [x :as request] ....)


(GET "/path/:x" request
  :path-params [x :- s/Int]

ikitommi 2018-08-09T17:15:05.000422Z

@alexkeyes to use swagger, you just need to generate a valid swagger.json. ring-swagger helps if you are using Schema already, e.g. it does Schema => Swagger conversion. For clojure.spec, spec-tools library will help.

ikitommi 2018-08-09T17:15:47.000135Z

If using neither, just generate a swaggee.json by hand and serve it yourself.

ikitommi 2018-08-09T17:16:13.000300Z

For compojure-users, compojure-api is the way.

vuuvi 2018-08-09T17:40:47.000243Z

so just to clarify, what does the generation of the swagger.json file? compojure-api (if I decide to use it?)

vuuvi 2018-08-09T17:54:13.000315Z

I mean to say I’m at the point where I understand what swagger is and what it needs to work, I just haven’t grokked how we can take clojure code and make it understand an API

ikitommi 2018-08-09T17:55:43.000196Z

in compojure-api, there is a ring handler api, which takes options map and the compojure(-api) routes. It creates the ring-swagger data based on the routes and puts the data into request for the swagger-handler to use at runtime.

ikitommi 2018-08-09T17:57:18.000057Z

(require '[compojure.api.sweet :refer :all])
(require '[ring.util.http-response :refer :all])

(def app
     {:ui "/api-docs"
      :spec "/swagger.json"}}
    (GET "/hello" []
      (ok {:message "hello"})}))))

ikitommi 2018-08-09T17:57:39.000248Z

is the minimalistic swagger-app.

vuuvi 2018-08-09T17:57:50.000248Z

okay I think I am understanding…

vuuvi 2018-08-09T17:58:30.000111Z

lein run will use the api macro to generate the json needed for swagger?

ikitommi 2018-08-09T17:59:35.000141Z

api is a function. which return a ring handler. when it’s evaluated, it creates the swagger-data once. c-api has no extra macros, besides the ones from compojure.

vuuvi 2018-08-09T18:00:37.000132Z


vuuvi 2018-08-09T18:04:55.000564Z

okay I think I get it!

vuuvi 2018-08-09T18:05:15.000123Z


ikitommi 2018-08-09T18:08:07.000102Z

ole hyvä!

mgrbyte 2018-08-09T18:59:51.000023Z

great, thanks! Couple of questions.. Does the 2nd form enable swagger docs whilst the 1st doesn't? Do both of those work with compojure.api.sweet/resource?

ikitommi 2018-08-09T19:02:34.000154Z

the normal compojure syntax (1st) doesn't contribute to swagger docs. The latter does (as it's c-api addon).

ikitommi 2018-08-09T19:03:34.000100Z

in resource, the :handler is just a function of request => response, so no special syntax involved

ikitommi 2018-08-09T19:03:56.000255Z

ping @mgrbyte

mgrbyte 2018-08-09T19:11:10.000163Z

thanks! :thumbsup: