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 (the0.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.

theCHANGELOG.

[metosin/compojure-api"1.0.0"]

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'thave to usedefroutes, just usedef ordefn instead:

(defnmore-routes [db version]  (routes    (GET"/version" []      (ok {:version version}))    (POST"/thingie" []      (ok (thingie/create db)))))(defnapp [db]  (api    (context"/api/:version" []:path-params [version:- s/Str]      (more-routes db version)      (GET"/kikka" []        (ok"kukka")))))

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 ofcompojure.core under your apis and remove/resolve those. There are now modified versions ofroutes andlet-routes incompojure.api.core &compojure.api.sweet.

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

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

• swagger-ui andswagger-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)

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

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

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

If you have used:coercion options with the api - when compiling theapi form, youmight 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.

Renamemiddlewares calls tomiddleware. 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 {:option1})];; NEW - VECTOR:middleware [wrap-bar [wrap-foo {:option1}]];; NEW - ANONYMOUS FUNCTION:middleware [wrap-bar #(wrap-foo % {:option1})]

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

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.

"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) viaapi option:api :invalid-routes-fn.Seetests for details
3. wrap routes which are not meant to produce any docs withundocumented => will not produce anyerrors regardless of the api-settings

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

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 shoutcompojure-api at #clojure on Freenode to summon someone. Or you can file an issue or update this guide.

All feedback welcome.

Enjoy.