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.

Middlewares

TODO

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.