Migration Guide to 1.0.0

About

1.0.0 is a big release with lot's of small breaking changes - for the better! We have tried to make the migration as smooth as possible; with most/all things should break nicely at compile-time, with informative error messages.

NOTE If you are currently not using the latest pre-1.0.0 version (the 0.24.5), update first to it and see if you apis compile ok. We have dropped some of the old deprecation warnings/errors from 1.0.0.

Read

the CHANGELOG.

Update the dependency

[metosin/compojure-api "1.0.0"]

Convert route-macros

Find and replace the following:

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

NOTE: subroutes can be defined 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

Swagger artefacts

• swagger-ui and swagger-docs are deprecated (and thus - removed from sweet). Convert them either to:
  • swagger-routes (allows separate middleware to be applied)
  • api-options under :swagger (keeps all configuration in one place)

old format

(api
  (swagger-ui "/api-docs" 
              {:validatorUrl nil, :swagger-docs "/swagger2.json"})
  (swagger-docs "/swagger2.json"
                {:basePath "/app"
                 :info {:title "Swagger api"}})
  ...)

swagger-routes

(api
  (swagger-routes
     {:ui "/api-docs" 
      :spec "/swagger2.json"
      :options {:ui {:validatorUrl nil}}
      :data {:basePath "/app"
             :info {:title "Swagger api"}}})
  ...)

api-options

(api
  {:swagger
   {:ui "/api-docs"
    :spec "/swagger2.json"
    :options {:ui {:validatorUrl nil}}
    :data {:basePath "/app"
           :info {:title "Swagger api"}}}
   ...)

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

If you have created custom dispatch functions, you might get these error messages when compiling your apis:

":middlewares is deprecated with 1.0.0, use :middleware instead."

or

":parameters is deprecated with 1.0.0, use :swagger instead."

Changing those should be streightforward. See previous chapter for details on the new syntax.

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 having issues?

If this guide is missing something relevant, feel free to update it.

If you need help, you find us on Slack - https://clojurians.slack.com/messages/ring-swagger/ or you can shout compojure-api at #clojure on Freenode to summon someone. Or you can file an issue or update this guide.

All feedback welcome.

All good?

Enjoy.