[Question] Including routes from another namespace into the Swagger docs

[mablack]

I'm fairly new to Clojure, so I could be doing something wrong here, but I was hoping to get some advice on structuring a project.

I'm working on a web API project, and I've split the files up into something like this:

/
  |- src/
    |- test_api/
      |- handler.clj
      |- routes/
        |- product.clj  

The idea is to split the routes that are grouped by context out into their own files; i.e. routes/product.clj contains the routes for the /products context.

I've found that the swagger docs for the defroutes* nested in the context defined in routes/product.clj don't get generated unless I explicitly :refer to them in handler.clj - I'd prefer to only use :require :as so I can refer to them under their namespaces.

I've included examples of the code below. handler.clj has some comments showing which version of the :require statements work, and which version doesn't.

handler.clj

(ns test-api.handler
  (:require [compojure.api.sweet :refer :all]
            [ring.util.http-response :refer :all]
            [schema.core :as s]
            ;; the line below generates the correct swagger docs
            [test-api.routes.product :as productroutes :refer [product-routes get-product-by-id get-products-by-barcode]]
            ;; the line below doesn't generate the docs for the '/products/:id' or '/products/barcode/:barcode' routes, but 
            ;; docs for 'products/test' will be generated
            ;;[test-api.routes.product :as productroutes :refer [product-routes]]
            ))

(s/defschema Result {:result Long})

(defapi app
  (swagger-ui)
  (swagger-docs
    :title "Test-api Api"
    :description "this is Test-api Api.")
  (swaggered "products"
     :description "products api"
     productroutes/product-routes)
  (swaggered "math"
    :description "playing with parameters"
    (GET* "/plus" []
      :return Result
      :query-params [x :- Long, {y :- Long 1}]
      :summary "x+y (y default to 1)"
      (ok {:result (+ x y)}))))

routes/product.clj

(ns test-api.routes.product
  (:require [compojure.api.sweet :refer :all]
            [ring.util.http-response :refer :all]
            [schema.core :as s]
            [test-api.services.product-services :as product-service]
            [test-api.data.mockdata :refer [db]]))


(defroutes* get-product-by-id
  (GET* "/:id" []
    :summary "get a product by id"
    :path-params [id :- Long]
    (ok (product-service/get-product-by-id db id))))

(defroutes* get-products-by-barcode
  (GET* "/barcode/:barcode" []
          :summary "get products with matching barcode"
          :path-params [barcode :- String]
          :query-params [lon :- Double, lat :- Double]
          (ok (product-service/find-products-by-barcode-and-location db barcode lon lat))))


(defroutes* product-routes
  (context "/products" []
    get-product-by-id
    get-products-by-barcode
    (GET* "/test" []
          (ok "test"))
           ))

Is there a way to get this working without including the routes explicitly?
Thanks in advance for any advice you can give me!

[ikitommi]

hi.

the root reason for this is the same as in #33. The current implementation for defroutes* is really bad as it doesn't resolve the required namespaces correctly for swagger docs -part.

current workaround: refer the names into root namespace.

future solution: will port the libs for Swagger 2.0, which helps to build the defroutes* more clean. I'll try to find time for this (as also suffering from the same thing in projects).

I'll add this to readme so that people know this issue.

[mablack]

Ok, that makes sense - I'll look forward to the Swagger 2.0 implementation. thanks for your help @ikitommi :)

[trptcolin]

I'm running up against this issue as well, and I'm happy to do the workaround but I had a rough time getting an empty routes collection for the routes I'm referring into the ns. I actually had things working in a trimmed-down example, but I had a hard time figuring out the difference between the small example and the one that fails for me.

Here's where things appear to go wrong (I'm essentially tracing the internal behavior of extract-routes):

services.core=> (->> [:description "products api" 'product/product-routes] swagger/peel swagger/macroexpand-to-compojure)
[:description "products api" ((context "/products" [] (PUT* "/test" [] :summary "hi" {:status 200, :body "test"})))]
services.core=> (->> [:description "products api" 'product/product-routes] swagger/peel swagger/macroexpand-to-compojure swagger/collect-compojure-routes)
[:description "products api" (#compojure.api.swagger.CompojureRoutes{:p "/products", :c ()})]

I'd hoped it to be more like my (working) copy of the case listed above, which does this:

fubar.core=> (->> [:description "products api" 'other/product-routes] swagger/peel swagger/macroexpand-to-compojure)
[:description "products api" ((context "/products" [] ((compojure.core/GET "/test" [:as +compojure-api-request+] (do "test")))))]
fubar.core=> (->> [:description "products api" 'other/product-routes] swagger/peel swagger/macroexpand-to-compojure swagger/collect-compojure-routes)
[:description "products api" ((context "/products" [] (#compojure.api.swagger.CompojureRoute{:p "/test", :b (compojure.core/GET "/test" [:as +compojure-api-request+] (do "test"))})))]

So the collect-compojure-routes appears, in one way or another, to be the place that's having a hard time.

The difference here appears to be that using GET* works, but PUT* does not. POST* also appears to work. I don't have time to dig any further now, but wanted to get this info out there to save others some time.

[trptcolin]

Ah I see what caused my issue with PUT* - looks like it wasn't originally referred in my root handler. So in addition to the handlers themselves, it looks like things like GET*, POST*, PUT*, etc. also need to be referred (not sure what all else is hidden by that "etc." I just typed. But at any rate, consider me worked around! Hope this is helpful to someone.