Migration Guide to 1.0.0

Read

the CHANGELOG.

Update the dependency

[metosin/compojure-api "1.0.0-SNAPSHOT"]

Convert route-macros

Find and replace the following:

• GET* => GET
• ANY* => ANY
• HEAD* => HEAD
• PATCH* => PATCH
• DELETE* => DELETE
• OPTIONS* => OPTIONS
• POST* => PUT
• context* => context
• defroutes* => defroutes

NOTE: subroutes can be defines as normal Clojure values/functions, so you don't have to use defroutes, just use def or defn instead:

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

Replace vanilla compojure-routes under your api

Vanilla Compojure routes will not produce any swagger-docs (as they do not satisfy the Routing protocol). They can still be used for handling request, just without docs.

• find usages of compojure.core under your apis and remove/resolve those. There are now modified versions of routes and let-routes in compojure.api.core & compojure.api.sweet.

• the following are removed from sweet: let-request, routing, wrap-routes

  • replace them somehow, or just accept do docs will be generated

Api-level coercion

If you have used :coercion options with the api - when compiling the api form, you might get AssertionError saying:

"ERROR: Option [:coercion] should be a funtion of request->type->matcher, got a map instead. From 1.0.0 onwards, you should wrap your type->matcher map into a request-> function. If you want to apply the matchers for all request types, wrap your option with 'constantly'"

Act accordingly.

Middleware

Rename middlewares calls to middleware. Rename :middlewares restructuring to :middleware.

Define middleware as vector of middleware functions, or vectors of middleware functions and parameters. When a vector is seen, the first item is used as middleware function and the rest are passed in as options to the function. Another way to set middleware options is using anonymous function.

;; OLD
:middleware [wrap-bar (wrap-foo {:option 1})]
;; NEW - VECTOR
:middleware [wrap-bar [wrap-foo {:option 1}]]
;; NEW - ANONYMOUS FUNCTION
:middleware [wrap-bar #(wrap-foo % {:option 1})]

The reason for this change is that it makes it easier for Compojure-api to handle middleware as data. Duct uses similar format.

Custom restructure-param methods

:middlewares key is renamed to :middleware.

Seeing extra WARNINGs?

"Not all child routes satisfy compojure.api.routing/Routing."

... the routes do work, but no swagger-docs are generated. You have the following options:

1. do nothing
2. change handling of missing routes (to ignore or to throw exception) via api option :api :invalid-routes-fn. See tests for details
3. wrap routes which are not meant to produce any docs with undocumented => will not produce any errors regardless of the api-settings

(api
  (undocumented
    my-vanilla-ring-handler
    (resources "/" {:root "public"}))
  (context "/api" []
    ...))

Still some issues?

Goto https://clojurians.slack.com/messages/ring-swagger/, yell 'compojure-api' at #clojure on Freenode, file an issue or update this guide.

All good?

Enjoy.