Sweet web apis with Compojure & Swagger
EPL-1.0 License
Bot releases are visible (Hide)
(defn more-routes [db version]
(routes
(GET "/version" []
(ok {:version version}))
(POST "/thingie" []
(ok (thingie/create db)))))
(defn app [db]
(api
(context "/api/:version" []
:path-params [version :- s/Str]
(more-routes db version)
(GET "/kikka" []
(ok "kukka")))))
Routing
protocol. They can still be used for handling request, just without docs.
[:api :invalid-routes-fn]
to declare how to handle routes not satisfyingRouting
protocol. Default implementation logs invalid routes as WARNINGs.compojure.api.sweet
:
let-request
, routing
, wrap-routes
*
) is removed from route macro & function names, as there is no reason to mix compojure-api & compojure route macros.
GET*
=> GET
ANY*
=> ANY
HEAD*
=> HEAD
PATCH*
=> PATCH
DELETE*
=> DELETE
OPTIONS*
=> OPTIONS
POST*
=> PUT
context*
=> context
defroutes*
=> defroutes
swagger-docs
and swagger-ui
are now longer in compojure.api.sweet
:swagger
(has no defaults)swagger-routes
function, mounting both the swagger-ui
and swagger-docs
and wiring them together
/
and the swagger-spec to /swagger.json
swagger-ui
& swagger-docs
(need to be separately imported from compojure.api.swagger
).(defapi app
(swagger-routes)
(GET "/ping" []
(ok {:message "pong"})))
(defapi app
{:swagger {:ui "/", :spec "/swagger.json"}}
(GET "/ping" []
(ok {:message "pong"})))
request => type => matcher
as it is documented.type => matcher
map. Options are checked against type => matcher
coercion input, and amiddlewares
to middleware
and :middlewares
key (restructuring) to :middleware
[function args]
[[wrap-foo {:opts :bar}]]
[#(wrap-foo % {:opts :bar})]
[(fn [handler] (wrap-foo handler {:opts :bar}))]
:parameters
key used by restructure-param
:swagger
.
public-resource-routes
& public-resources
are removed from compojure.api.middleware
.compojure.api.legacy
namespace has been removed.https://github.com/metosin/compojure-api/wiki/Migration-Guide-to-1.0.0
compojure.api.core
:
routes
& letroutes
, just like in the Compojure, but supporting Routing
undocumented
- works just like routes
but without any route definitions. Can be used to wrap legacy routes which setting the api option to fail on missing docs.api
is now just function, not a macro. It takes an optional options maps and a top-level route function.(fact "coercion is on for apiless routes"
(let [route (GET "/x" []
:query-params [x :- Long]
(ok))]
(route {:request-method :get :uri "/x" :query-params {}}) => throws))
[backtick "0.3.3"]
Published by Deraen over 8 years ago
Published by Deraen almost 9 years ago
compojure.api.exception/with-logging
helper to add logging to exception handlers.
[metosin/ring-swagger "0.22.3"] is available
Published by Deraen almost 9 years ago
[metosin/ring-swagger "0.22.2"] is available
[metosin/ring-swagger-ui "2.1.4-0"] is available
[potemkin "0.4.3"] is available
Published by Deraen almost 9 years ago
[prismatic/schema "1.0.4"] is available but we use "1.0.3"
Published by Deraen almost 9 years ago
schema
& matcher
-input) for better performance.
api
and reading json-string out.[potemkin "0.4.2"] is available but we use "0.4.1"
Published by Deraen almost 9 years ago
[Ring-Swagger "0.22.1"]
clojure.tools.logging
is used with default uncaugt exception handling if it's foundapi
and defapi
produce identical swagger-docs. Fixes #159
[metosin/ring-swagger "0.22.1"] is available but we use "0.22.0"
[metosin/ring-swagger-ui "2.1.3-4"] is available but we use "2.1.3-2"
[prismatic/plumbing "0.5.2] is available but we use "0.5.1"
Published by Deraen almost 9 years ago
swagger-ui
now supports passing arbitrary options to SwaggerUI
[prismatic/schema "1.0.3"] is available but we use "0.4.4"
[prismatic/plumbing "0.5.1] is available but we use "0.4.4"
[metosin/schema-tools "0.7.0"] is available but we use "0.5.2"
[metosin/ring-swagger "0.22.0"] is available but we use "0.21.0"
[metosin/ring-swagger-ui "2.1.3-2"] is available but we use "2.1.2"
Published by Deraen almost 9 years ago
:query-params [x :- [Long]]
& url ?x=1&x=2&x=3
should result in x
being [1 2 3]
.:validation-errors :error-handler
, :validation-errors :catch-core-errors?
:exceptions :exception-handler
options have been removed.
:exceptions :handlers
options.context
from compojure.api.sweet
to compojure.api.legacy
. Use context*
instead.[metosin/ring-swagger "0.21.0-SNAPSHOT"] is available but we use "0.20.4"
[compojure "1.4.0"] is available but we use "1.3.4"
[prismatic/schema "0.4.4"] is available but we use "0.4.3"
[metosin/ring-http-response "0.6.5"] is available but we use "0.6.3"
[metosin/schema-tools "0.5.2"] is available but we use "0.5.1"
[metosin/ring-swagger-ui "2.1.2"] is available but we use "2.1.5-M2"
[peridot "0.4.1"] is available but we use "0.4.0"
Published by Deraen almost 9 years ago
:components
-option of api-middleware
or wrap-components
-middleware:components
-restructuring:coercion
. See thethe tests.
ring-request->coercion-type->coercion-matcher
allowing protocol-based coercion in the futuresrc-coerce
, they will break (nicely at compile-time):swagger
just for swagger-docs. Does not do any coercion.(GET* "/documented" []
:swagger {:responses {200 {:schema User}
404 {:schema Error
:description "Not Found"} }
:paramerers {:query {:q s/Str}
:body NewUser}}}
...)
[cheshire "5.5.0"] is available but we use "5.4.0"
[backtick "0.3.3"] is available but we use "0.3.2"
[lein-ring "0.9.6"] is available but we use "0.9.4"
Published by Deraen over 9 years ago
:multipart-params
now sets :consumes ["multipart/form-data"]
and :form-params
sets:consumes ["application/x-www-form-urlencoded"]
compojure.api.upload
namespace.(POST* "/upload" []
:multipart-params [file :- TempFileUpload]
:middlewares [wrap-multipart-params]
(ok (dissoc file :tempfile))))
:responses
. A helpful IllegalArgumentException
will be thrown at compile-time with old models.:responses {400 {:schema ErrorSchema}}
:responses {400 {:schema ErrorSchema, :description "Eror"}}
api-middleware
options with key :ring-swagger
:(defapi app
{:ring-swagger {:ignore-missing-mappings? true}})
(swagger-docs)
(swagger-ui)
...)
path-for
:(fact "bidirectional routing"
(let [app (api
(GET* "/api/pong" []
:name :pong
(ok {:pong "pong"}))
(GET* "/api/ping" []
(moved-permanently (path-for :pong))))]
(fact "path-for resolution"
(let [[status body] (get* app "/api/ping" {})]
status => 200
body => {:pong "pong"}))))
(require '[compojure.api.sweet :refer :all])
(require '[compojure.api.swagger :refer [validate])
(defrecord NonSwaggerRecord [data])
(def app
(validate
(api
(swagger-docs)
(GET* "/ping" []
:return NonSwaggerRecord
(ok (->NonSwaggerRecord "ping"))))))
; clojure.lang.Compiler$CompilerException: java.lang.IllegalArgumentException:
; don't know how to create json-type of: class compojure.api.core_integration_test.NonSwaggerRecord
[metosin/ring-swagger "0.20.4"] is available but we use "0.20.3"
[metosin/ring-http-response "0.6.2"] is available but we use "0.6.1"
[metosin/ring-swagger-ui "2.1.5-M2"]
[prismatic/plumbing "0.4.4"] is available but we use "0.4.3"
[prismatic/schema "0.4.3"] is available but we use "0.4.2"
Published by Deraen over 9 years ago
with-meta
), fixes #96
(context* "/responses" []
:tags ["responses"]
(GET* "/" []
:query-params [return :- (s/enum :200 :403 :404)]
:responses {403 ^{:message "spiders?"} {:code s/Str} ; old
404 (with-meta {:reason s/Str} {:message "lost?"})} ; new
:return Total
:summary "multiple returns models"
(case return
:200 (ok {:total 42})
:403 (forbidden {:code "forest"})
:404 (not-found {:reason "lost"}))))
Published by Deraen over 9 years ago
compojure.api.core/api
, the work-horse behind compojure.api.core/defapi
.api
, pushed to request via ring-swagger middlewares.
+compojure-api-routes+
littering the handler namespaces.[metosin/ring-swagger "0.20.3"] is available but we use "0.20.2"
[prismatic/plumbing "0.4.3"] is available but we use "0.4.2"
[peridot "0.4.0"] is available but we use "0.3.1"
[compojure "1.3.4"] is available but we use "1.3.3"
[lein-ring "0.9.4"] is available but we use "0.9.3"
Published by Deraen over 9 years ago
[metosin/ring-swagger "0.20.2"] is available but we use "0.20.0"
[prismatic/schema "0.4.2"] is available but we use "0.4.1"
Published by Deraen over 9 years ago
:no-docs
(a boolean) - endpoints with this don't get api documentation.defroutes*
now does namespace resolution for the sourcedefroutes*
are now automatically accessed over a Var for better development flow.ring.swagger.json-schema/describe
is now imported into compojure.api.sweet
for easy use. If your codedefapi
or compojure.api.routes/api-root
within that)compojure.api.routes/with-routes
is now compojure.api.routes/api-root
[metosin/ring-swagger-ui "2.1.1-M2"]
to get things pre-configured2.1.1-M2
yourself from the source.:nickname
is now :operationId
:notes
is now :description
swagger-docs
now takes any valid Swagger Spec data in. Using old format gives a warning is to STDOUT.(swagger-docs
{:info {:version "1.0.0"
:title "Sausages"
:description "Sausage description"
:termsOfService "http://helloreverb.com/terms/"
:contact {:name "My API Team"
:email "[email protected]"
:url "http://www.metosin.fi"}
:license {:name "Eclipse Public License"
:url "http://www.eclipse.org/legal/epl-v10.html"}}
:tags [{:name "kikka", :description "kukka"}]})
/api/api-docs
to /swagger.json
.compojure.api.swagger/swaggered
is deprecated - not relevant with 2.0. Works, but prints out a warning to STDOUT(GET* "/api/pets/" []
:tags ["pet"]
(ok ...))
(context* "/api/pets" []
:tags ["pet"]
(GET* "/" []
:summary "get all pets"
(ok ...)))
[metosin/ring-swagger "0.20.0"] is available but we use "0.19.4"
[prismatic/schema "0.4.1"] is available but we use "0.4.0"
Published by Deraen over 9 years ago
[prismatic/plumbing "0.4.2"] is available but we use "0.4.1"
[prismatic/schema "0.4.1"] is available but we use "0.4.0"
[potemkin "0.3.13"] is available but we use "0.3.12"
[compojure "1.3.3"] is available but we use "1.3.2"
[metosin/ring-swagger "0.19.4"] is available but we use "0.19.3"