Swagger options identical to compojure-api

CHANGES.md

@@ -1,7 +1,28 @@
 ## 0.3.0-SNAPSHOT
 
-* *BREAKING*: Removed type-level interceptors from ring-adapter.
+* **BREAKING**: Removed type-level interceptors from ring-adapter.
 * Support for Context-based urls, thanks to [Wout Neirynck](https://github.com/wneirynck).
+* **BREAKING**: top-level swagger options are now in align to the compojure-api:
+  * Fixes [#22](https://github.com/metosin/kekkonen/issues/22)
+  * By default, `api`s don't bind swagger-spec & swagger-ui, use `:spec` & `:ui` options
+
+### Old
+
+```clj
+{:swagger {:info {:title "Kekkonen"}}
+ :swagger-ui {:jsonEdit true}})
+```
+
+### New
+
+```clj
+{:swagger
+ {:spec "/swagger.json"
+  :ui "/api-docs"
+  :options {:ui {:jsonEdit true}
+            :spec {:ignore-missing-mappings? false}}
+  :data {:info {:title "Kekkonen"}}}}
+```
 
 * updated dependencies:
 

README.md

@@ -137,7 +137,7 @@ Mostly written as [issues](https://github.com/metosin/kekkonen/issues). Biggest
   (success {:result (+ x y)}))
 
 (defnk ^:command inc!
-  [[:components counter]]
+  [counter]
   (success {:result (swap! counter inc)}))
 
 ;;
@@ -146,10 +146,12 @@ Mostly written as [issues](https://github.com/metosin/kekkonen/issues). Biggest
 
 (def app
   (cqrs-api
-    {:swagger {:info {:title "Kekkonen example"}}
+    {:swagger {:ui "/api-docs"
+               :spec "/swagger.json"
+               :data {:info {:title "Kekkonen example"}}}
      :core {:handlers {:api {:pizza #'echo-pizza
                              :example [#'ping #'inc! #'plus]}}
-            :context {:components {:counter (atom 0)}}}}))
+            :context {:counter (atom 0)}}}))
 
 ;;
 ;; Start it

dev-src/example/api.clj

@@ -41,7 +41,9 @@
 
 (def app
   (cqrs-api
-    {:swagger {:info {:title "Kekkonen example"}}
+    {:swagger {:ui "/api-docs"
+               :spec "/swagger.json"
+               :data {:info {:title "Kekkonen example"}}}
      :core {:handlers {:api {:pizza #'echo-pizza
                              :sample [#'ping #'inc! #'plus]}}
             :context {:components {:counter (atom 0)}}}}))

dev-src/example/cqrs.clj

@@ -105,7 +105,9 @@
 
 (def app
   (cqrs-api
-    {:swagger {:info {:title "Kekkonen"}}
+    {:swagger {:ui "/api-docs"
+               :spec "/swagger.json"
+               :data {:info {:title "Kekkonen"}}}
      :core {:handlers {:api {:item [#'get-items #'add-item #'reset-items]
                              :calculator [#'plus #'times #'increment]
                              :security #'get-user

dev-src/example/github/github.clj

@@ -112,8 +112,10 @@
 
 (def app
   (cqrs-api
-    {:swagger {:info {:title "Kekkonen"
-                      :version "1.0"}}
+    {:swagger {:ui "/api-docs"
+               :spec "/swagger.json"
+               :data {:info {:title "Kekkonen"
+                             :version "1.0"}}}
      :core {:handlers {:api {:github [#'get-repository
                                       #'list-repositorys
                                       #'fork

examples/component/src/sample/handler.clj

@@ -38,8 +38,10 @@
 
 (p/defnk create [[:state counter]]
   (cqrs-api
-    {:swagger {:info {:title "Kekkonen with Component"
-                      :description "created with http://kekkonen.io"}}
+    {:swagger {:ui "/api-docs"
+               :spec "/swagger.json"
+               :data {:info {:title "Kekkonen with Component"
+                             :description "created with http://kekkonen.io"}}}
      :core {:handlers {:api {:pizza #'echo-pizza
                              :math [#'inc! #'plus]
                              :ping #'ping}}

src/kekkonen/api.clj

@@ -11,8 +11,7 @@
    (s/optional-key :api) {:handlers k/KeywordMap}
    (s/optional-key :ring) r/Options
    (s/optional-key :mw) k/KeywordMap
-   (s/optional-key :swagger) k/KeywordMap
-   (s/optional-key :swagger-ui) k/KeywordMap})
+   (s/optional-key :swagger) ks/Options})
 
 (s/def +default-options+ :- Options
   {:core (-> k/+default-options+
@@ -21,18 +20,21 @@
    :api {:handlers r/+kekkonen-handlers+}
    :ring r/+default-options+
    :mw mw/+default-options+
-   :swagger {:info {:title "Kekkonen API"}}
-   :swagger-ui ks/+default-swagger-ui-options+})
+   :swagger {:data {:info {:title "Kekkonen API"
+                           :version "0.0.1"}}}})
 
 (defn api [options]
   (s/with-fn-validation
     (let [options (s/validate Options (kc/deep-merge-map-like +default-options+ options))
-          swagger (merge (:swagger options) (mw/api-info (:mw options)))
-          dispatcher (-> (k/dispatcher (:core options))
-                         (k/inject (-> options :api :handlers))
-                         (k/inject (ks/swagger-handler swagger options)))]
+          api-handlers (-> options :api :handlers)
+          swagger-data (merge (-> options :swagger :data) (mw/api-info (:mw options)))
+          swagger-options (-> options :swagger)
+          swagger-handler (ks/swagger-handler swagger-data swagger-options)
+          dispatcher (cond-> (k/dispatcher (:core options))
+                             api-handlers (k/inject api-handlers)
+                             swagger-handler (k/inject swagger-handler))]
       (mw/wrap-api
         (r/routes
           [(r/ring-handler dispatcher (:ring options))
-           (ks/swagger-ui (:swagger-ui options))])
+           (ks/swagger-ui swagger-options)])
         (:mw options)))))

src/kekkonen/core.clj

@@ -594,6 +594,7 @@
           :no-doc nil
           ;; TODO: should this be defined in kekkonen.ring?
           :responses nil}})
+
 (s/defn dispatcher :- Dispatcher
   "Creates a Dispatcher"
   [options :- Options]
@@ -618,7 +619,7 @@
 
 (s/defn inject
   "Injects handlers into an existing Dispatcher"
-  [dispatcher :- Dispatcher, handlers]
+  [dispatcher :- Dispatcher, handlers :- (s/constrained s/Any (complement nil?) 'not-nil)]
   (if handlers
     (let [handler (collect-and-enrich
                     (merge dispatcher {:handlers handlers :type-resolver any-type-resolver}) true)]

src/kekkonen/cqrs.clj

@@ -47,7 +47,7 @@
   (ka/api
     (kc/deep-merge-map-like
       {:core {:type-resolver (k/type-resolver :command :query)}
-       :swagger {:info {:title "Kekkonen CQRS API"}}
+       :swagger {:data {:info {:title "Kekkonen CQRS API"}}}
        :ring {:types {:query {:methods #{:get}
                               :parameters {[:data] [:request :query-params]}}
                       :command {:methods #{:post}

src/kekkonen/http.clj

@@ -9,7 +9,7 @@
   (ka/api
     (kc/deep-merge-map-like
       {:core {:type-resolver (k/type-resolver :get :head :patch :delete :options :post :put :any)}
-       :swagger {:info {:title "Kekkonen HTTP API"}}
+       :swagger {:data {:info {:title "Kekkonen HTTP API"}}}
        :ring {:types {:get {:methods #{:get}}
                       :head {:methods #{:head}}
                       :patch {:methods #{:patch}}

src/kekkonen/ring.clj

@@ -167,8 +167,8 @@
 
 (s/defn routes :- k/Function
   "Creates a ring handler of multiples handlers, matches in order."
-  [ring-handlers :- [k/Function]]
-  (apply some-fn ring-handlers))
+  [ring-handlers :- [(s/maybe k/Function)]]
+  (apply some-fn (keep identity ring-handlers)))
 
 (s/defn match
   "Creates a ring-handler for given uri & request-method"

src/kekkonen/swagger.clj

@@ -6,10 +6,15 @@
             [kekkonen.core :as k]
             [kekkonen.common :as kc]
             [plumbing.core :as p]
-            [kekkonen.ring :as r]))
+            [kekkonen.ring :as r]
+            [clojure.string :as str]))
 
-(def +default-swagger-ui-options+
-  {:path "/"})
+(s/defschema Options
+  {(s/optional-key :ui) (s/maybe s/Str)
+   (s/optional-key :spec) (s/maybe s/Str)
+   (s/optional-key :data) k/KeywordMap
+   (s/optional-key :options) {(s/optional-key :ui) k/KeywordMap
+                              (s/optional-key :spec) k/KeywordMap}})
 
 (defn transform-handler
   "Transforms a handler into ring-swagger path->method->operation map."
@@ -47,8 +52,11 @@
 
 (s/defn swagger-ui
   "Ring handler for the Swagger UI"
-  [options]
-  (apply ui/swagger-ui (into [(:path options)] (apply concat (dissoc options :path)))))
+  [{:keys [ui spec] :as options}]
+  (when ui
+    (apply ui/swagger-ui (into [ui] (apply concat (merge
+                                                    {:swagger-docs spec}
+                                                    (-> options :options :ui)))))))
 
 (defn- add-base-path
   "Extracts the base path from the context and adds it to the swagger map as basePath"
@@ -57,16 +65,19 @@
     (assoc swagger :basePath context)
     swagger))
 
-(defn swagger-handler [swagger options]
-  (k/handler
-    {:type :kekkonen.ring/handler
-     :kekkonen.ring/method :get
-     :name "swagger.json"
-     :no-doc true}
-    (fn [{:keys [request] :as context}]
-      (let [dispatcher (k/get-dispatcher context)
-            ns (some-> context :request :query-params :ns str keyword)
-            handlers (k/available-handlers dispatcher ns (#'r/clean-context context))]
-        (ok (swagger-object
-              (add-base-path request (ring-swagger handlers swagger))
-              options))))))
+(defn swagger-handler
+  "Creates a handler, that serves the swagger-spec"
+  [swagger options]
+  (if-let [spec (:spec options)]
+    (k/handler
+      {:type :kekkonen.ring/handler
+       :kekkonen.ring/method :get
+       :name spec
+       :no-doc true}
+      (fn [{:keys [request] :as context}]
+        (let [dispatcher (k/get-dispatcher context)
+              ns (some-> context :request :query-params :ns str keyword)
+              handlers (k/available-handlers dispatcher ns (#'r/clean-context context))]
+          (ok (swagger-object
+                (add-base-path request (ring-swagger handlers swagger))
+                (-> options :options :spec))))))))

test/kekkonen/api_test.clj

@@ -21,7 +21,9 @@
       context)))
 
 (facts "api-test"
-  (let [app (api {:core {:handlers {:api {:public [#'plus #'nada]
+  (let [app (api {:swagger {:ui "/api-docs"
+                            :spec "/swagger.json"}
+                  :core {:handlers {:api {:public [#'plus #'nada]
                                           secret-ns #'plus}}
                          :meta {::role require-role}}})]
 
@@ -294,12 +296,27 @@
                        {:/api/secret/plus anything})}))))
 
     (fact "swagger-ui"
-      (let [response (app {:uri "/" :request-method :get})]
+      (let [response (app {:uri "/api-docs" :request-method :get})]
         response => (contains
                       {:status 302
                        :body ""
                        :headers (contains
-                                  {"Location" "/index.html"})})))))
+                                  {"Location" "/api-docs/index.html"})})))))
+
+(facts "swagger-options"
+
+  (fact "ui & spec are not set by default"
+    (let [app (api {:core {:handlers {:api #'plus}}})]
+
+      (app {:uri "/swagger.json", :request-method :get}) => not-found?
+      (app {:uri "/", :request-method :get}) => not-found?))
+
+  (fact "with ui & spec"
+    (let [app (api {:swagger {:spec "/swagger.json", :ui "/api-docs"}
+                    :core {:handlers {:api #'plus}}})]
+
+      (app {:uri "/swagger.json", :request-method :get}) => ok?
+      (app {:uri "/api-docs/index.html", :request-method :get}) => ok?)))
 
 (facts "api-meta"
   (fact "meta can be presented as maps or vector of tuples"

test/kekkonen/core_test.clj

@@ -950,14 +950,20 @@
     (fact "going meta boing boing"
       (k/invoke d :api/names) => #{:dispatcher :handler :names})))
 
-(fact "handlers can be injected into existing dispatcher"
-  (let [d (-> (k/dispatcher {:handlers {:api (k/handler {:name :test} identity)}})
-              (k/inject (k/handler {:name :ping} identity)))]
-    d => (contains
-           {:handlers
-            (just
-              {:api/test anything
-               :ping anything})})))
+(fact "injecting handlers"
+
+  (fact "handlers can be injected"
+    (let [d (-> (k/dispatcher {:handlers {:api (k/handler {:name :test} identity)}})
+                (k/inject (k/handler {:name :ping} identity)))]
+      d => (contains
+             {:handlers
+              (just
+                {:api/test anything
+                 :ping anything})})))
+
+  (fact "injecting nil handlers fails"
+    (-> (k/dispatcher {:handlers {:api (k/handler {:name :test} identity)}})
+        (k/inject nil)) => schema-error?))
 
 (facts "coercion-matcher"
   (let [PositiveInt (s/both s/Int (s/pred pos? 'positive))

test/kekkonen/midje.clj

@@ -1,6 +1,7 @@
 (ns kekkonen.midje
   (:require [midje.util.exceptions :as e]
             [kekkonen.core :as k]
+            [schema.core :as s]
             [cheshire.core :as c]))
 
 (defn throws?
@@ -14,6 +15,7 @@
          (not (nil? x))
          (= mdata m))))))
 
+(def schema-error? (throws? {:type ::s/error}))
 (def missing-route? (throws? {:type ::k/dispatch}))
 (def input-coercion-error? (throws? {:type ::k/request}))
 (def output-coercion-error? (throws? {:type ::k/response}))

test/kekkonen/ring_test.clj

@@ -44,7 +44,7 @@
     (fact "request can be read as-is"
       (let [request {:uri "/api/snoop" :request-method :post}]
         (app request) => (ok request)))
-    
+
     (fact "handles request within context"
       (let [request {:uri "/somecontext/api/ping" :request-method :post :context "/somecontext"}]
         (app request) => "pong"))))

test/kekkonen/swagger_test.clj

@@ -51,22 +51,21 @@
 
     (fact "swagger-json can be generated"
       (s/with-fn-validation
-        (ks/swagger-object swagger {}) => truthy))))
+        (ks/swagger-object swagger {}) => some?))))
 
 (facts "swagger-handler"
   (let [dispatcher (k/transform-handlers
                      (k/dispatcher {:handlers {:api {:admin #'echo}}})
                      (partial #'r/attach-ring-meta r/+default-options+))
-        ctx {}
-        h (ks/swagger-handler {} {:info {:version "1.2.3"}})]
+        swagger-handler (ks/swagger-handler {} {:spec "swagger.json", :info {:version "1.2.3"}})]
+
     (against-background [(k/get-dispatcher anything) => dispatcher]
-
-	    (fact "generates swagger json"
-	      (:body (h ctx)) => (contains {:paths (as-checker not-empty)})))
-
-      (fact "extracts swagger basePath from request context"
-        (let [context-path "/testpath"]
-          (:body (h {:request {:context context-path}})) => (contains {:basePath context-path})))
-
-      (fact "does not add basePath if no context"
-        (-> (h {:request {}}) :body :basePath) => nil?)))
+      (fact "generates swagger json"
+        (swagger-handler {}) => (contains {:body (contains {:paths seq})})))
+
+    (fact "extracts swagger basePath from request context"
+      (let [context-path "/testpath"]
+        (:body (swagger-handler {:request {:context context-path}})) => (contains {:basePath context-path})))
+
+    (fact "does not add basePath if no context"
+      (-> (swagger-handler {:request {}}) :body :basePath) => nil)))