Fork me on GitHub
#ring-swagger
<
2018-08-09
>
vuuvi15:08:11

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

vuuvi15:08:58

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

vuuvi15:08:23

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

ikitommi15:08:11

are you using schema for coercion already?

ikitommi15:08:51

@mgrbyte

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

;;or

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

mgrbyte18:08:51

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?

ikitommi19:08:34

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

ikitommi19:08:34

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

mgrbyte19:08:10

thanks! :thumbsup:

ikitommi17:08:05

@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.

ikitommi17:08:47

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

ikitommi17:08:13

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

vuuvi17:08:47

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

vuuvi17:08:13

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

ikitommi17:08:43

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.

ikitommi17:08:18

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

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

ikitommi17:08:39

is the minimalistic swagger-app.

vuuvi17:08:50

okay I think I am understanding…

vuuvi17:08:30

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

ikitommi17:08:35

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.

vuuvi18:08:55

okay I think I get it!