Use new ring-swagger and test describing schemas

Author: Deraen

README.md

@@ -1,6 +1,6 @@
 # Compojure-api
 
-[![Build Status](https://travis-ci.org/metosin/compojure-api.png?branch=0.7.0)](https://travis-ci.org/metosin/compojure-api)
+[![Build Status](https://travis-ci.org/metosin/compojure-api.png)](https://travis-ci.org/metosin/compojure-api)
 
 Stuff on top of [Compojure](https://github.com/weavejester/compojure) for making sweet web apis.
 
@@ -286,7 +286,7 @@ you can also wrap models in containers (`vector` and `set`) and add extra metada
 ```clojure
   (POST* "/echos" []
     :return   [Thingie]
-    :body     [thingies #{Thingie} {:description "set on thingies"}]
+    :body     [thingies (describe #{Thingie} "set on thingies")]
     (ok thingies))
 ```
 

examples/src/examples/handler.clj

@@ -1,6 +1,7 @@
 (ns examples.handler
   (:require [compojure.api.sweet :refer :all]
             [ring.util.http-response :refer :all]
+            [ring.swagger.schema :refer [describe]]
             [examples.dates :refer :all]
             [examples.domain :refer :all]))
 
@@ -27,7 +28,8 @@
       :query  [query QueryParams]
       (ok query))
     (GET* "/sum" []
-      :query-params [x :- Long y :- Long]
+      :query-params [x :- (describe Long "first param")
+                     y :- (describe Long "second param")]
       :summary      "sums x & y query-parameters"
       (ok {:total (+ x y)}))
     (GET* "/times/:x/:y" []
@@ -58,7 +60,7 @@
           (ok (get-pizza id)))
         (POST* "/" []
           :return   Pizza
-          :body     [pizza NewPizza {:description "new pizza"}]
+          :body     [pizza (describe NewPizza "new pizza")]
           :summary  "Adds a pizza"
           :nickname "addPizza"
           (ok (add! pizza)))

examples/src/examples/thingie.clj

@@ -1,6 +1,7 @@
 (ns examples.thingie
   (:require [ring.util.http-response :refer :all]
             [compojure.api.sweet :refer :all]
+            [ring.swagger.schema :refer [field describe]]
             [schema.core :as s]))
 
 ;;
@@ -9,11 +10,13 @@
 
 (s/defschema Total {:total Long})
 
-(s/defschema Thingie {:id Long
-                      :hot Boolean
+(s/defschema Thingie {:id (describe Long "A integer")
+                      :hot (describe Boolean "yes or no")
                       :tag (s/enum :kikka :kukka)
-                      :chief [{:name String
-                               :type #{{:id String}}}]})
+                      :chief (describe
+                               [{:name String
+                                 :type #{{:id String}}}]
+                               "An array")})
 
 (s/defschema FlatThingie (dissoc Thingie :chief))
 
@@ -38,13 +41,16 @@
 
       (GET* "/plus" []
         :return       Total
-        :query-params [x :- Long {y :- Long 1}]
+        ;; You can add any keys to meta-data, but Swagger-ui might not show them
+        :query-params [x :- (describe Long "description")
+                       {y :- Long 1}]
         :summary      "x+y with query-parameters. y defaults to 1."
         (ok {:total (+ x y)}))
 
       (POST* "/minus" []
         :return      Total
-        :body-params [x :- Long y :- Long]
+        :body-params [x :- (describe Long "first param")
+                      y :- (describe Long "second param")]
         :summary     "x-y with body-parameters."
         (ok {:total (- x y)}))
 
@@ -63,15 +69,15 @@
   (swaggered "responses"
     :description "responses demo"
     (context "/responses" []
-  (POST* "/number" []
-         :return       Total
-         :query-params [x :- Long y :- Long]
-         :responses    {403 ^{:message "Underflow"} ErrorEnvelope}
-         :summary      "x-y with body-parameters."
-         (let [total (- x y)]
-              (if (>= total 0)
-                (ok {:total (- x y)})
-                (forbidden {:message "difference is negative"}))))))
+      (POST* "/number" []
+        :return       Total
+        :query-params [x :- Long y :- Long]
+        :responses    {403 ^{:message "Underflow"} ErrorEnvelope}
+        :summary      "x-y with body-parameters."
+        (let [total (- x y)]
+          (if (>= total 0)
+            (ok {:total (- x y)})
+            (forbidden {:message "difference is negative"}))))))
 
   (swaggered "primitives"
     :description "returning primitive values"
@@ -91,7 +97,7 @@
 
       (GET* "/hello" []
         :return String
-        :query-params [name :- String]
+        :query-params [name :- (describe String "foobar")]
         :notes   "<h1>hello world.</h1>"
         :summary "echos a string from query-params"
         (ok (str "hello, " name)))))
@@ -108,7 +114,7 @@
 
     (POST* "/body" []
       :return   Thingie
-      :body     [thingie Thingie]
+      :body     [thingie (describe Thingie "The request body")]
       :summary  "echoes a Thingie from json-body"
       (ok thingie))
 

project.clj

@@ -12,7 +12,7 @@
                  [compojure "1.1.8"]
                  [prismatic/schema "0.2.4"]
                  [metosin/ring-http-response "0.4.0"]
-                 [metosin/ring-swagger "0.10.6"]]
+                 [metosin/ring-swagger "0.11.0"]]
   :profiles {:thingie {:ring {:handler examples.thingie/app
                               :reload-paths ["src" "examples/src"]}
                        :source-paths ["examples/src"]

src/compojure/api/common.clj

@@ -61,5 +61,3 @@
     {}))
 
 (def meta-container? #{#'meta-container})
-
-

src/compojure/api/meta.clj

@@ -103,29 +103,25 @@
         (update-in [:parameters :responseMessages] (comp distinct concat) messages)
         (update-in [:responses] merge responses))))
 
-(defmethod restructure-param :body [_ [value model model-meta] acc]
+(defmethod restructure-param :body [_ [value model] acc]
   "reads body-params into a enchanced let. First parameter is the let symbol,
-   second is the Model to coerced! against, third parameter is optional meta-
-   data for the model. Examples:
-   :body [user User]
-   :body [user User {:key \"value\"}]"
+   second is the Model to coerced! against.
+   Examples:
+   :body [user User]"
   (-> acc
       (update-in [:lets] into [value (src-coerce! model :body-params :json)])
       (update-in [:parameters :parameters] conj {:type :body
-                                                 :model model
-                                                 :meta model-meta})))
+                                                 :model model})))
 
-(defmethod restructure-param :query [_ [value model model-meta] acc]
+(defmethod restructure-param :query [_ [value model] acc]
   "reads query-params into a enchanced let. First parameter is the let symbol,
-   second is the Model to coerced! against, third parameter is optional meta-
-   data for the model. Examples:
-   :query [user User]
-   :query [user User {:key \"value\"}]"
+   second is the Model to coerced! against.
+   Examples:
+   :query [user User]"
   (-> acc
       (update-in [:lets] into [value (src-coerce! model :query-params :query)])
       (update-in [:parameters :parameters] conj {:type :query
-                                                 :model model
-                                                 :meta model-meta})))
+                                                 :model model})))
 
 (defmethod restructure-param :body-params [_ body-params acc]
   "restructures body-params with plumbing letk notation. Example:

test/compojure/api/sweet_test.clj

@@ -3,6 +3,7 @@
             [schema.core :as s]
             [compojure.api.routes :as routes]
             [ring.mock.request :refer :all]
+            [ring.swagger.schema :refer [describe]]
             [cheshire.core :as cheshire]
             [compojure.core :as compojure]
             [compojure.api.sweet :refer :all]))
@@ -37,7 +38,7 @@
         identity)
       (POST* "/bands" []
         :return   Band
-        :body     [band [NewBand] {:description "new Band"}]
+        :body     [band [NewBand]]
         :summary  "Adds a Band"
         :nickname "addBand"
         identity)
@@ -55,7 +56,6 @@
         identity))))
 
 (facts "swaggered"
-
   (fact "details are generated"
     ((routes/get-routes) app-name)
 
@@ -80,8 +80,7 @@
                   :uri "/api/bands"
                   :metadata {:nickname "addBand"
                              :parameters [{:type :body
-                                           :model [NewBand]
-                                           :meta {:description "new Band"}}]
+                                           :model [NewBand]}]
                              :return Band
                              :summary "Adds a Band"}}
                  {:method :get