Clojurians Log v2

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

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

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

are you using schema for coercion already?

@mgrbyte

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

;;or

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

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

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

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

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

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

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.

(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"})}))))

is the minimalistic swagger-app.

okay I think I am understanding…

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

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.

okay

here’s the source: https://github.com/metosin/compojure-api/blob/master/src/compojure/api/api.clj#L19-L74

okay I think I get it!

Kiitos!

ole hyvä!

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?

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

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

ping @mgrbyte

thanks! :thumbsup: