compojure-api

compare

• Move from compile-time to runtime route resolution.
  • Most of the internal macro magic has been vaporized
  • Uses internally (invokable) Records & Protocols, allowing easier integration to 3rd party libs like Liberator
    • even for large apps (100+ routes), route compilation takes now millis, instead of seconds
  • sub-routes can be created with normal functions (or values), making it easier to:
    • pass in app-level dependencies from libs like Component
    • reuse shared request-handling time parameters like path-parameters and authorization info

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

Breaking changes

• BREAKING 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.
  • a new api-level option [:api :invalid-routes-fn] to declare how to handle routes not satisfying
    the Routing protocol. Default implementation logs invalid routes as WARNINGs.
• BREAKING compojure.core imports are removed from compojure.api.sweet:
  • let-request, routing, wrap-routes
• BREAKING Asterix (*) 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
• BREAKING swagger-docs and swagger-ui are now longer in compojure.api.sweet
  • Syntax was hairy and when configuring the spec-url it needed to be set to both in order to work
  • In future, there are multiple ways of setting the swagger stuff:
    • via api-options :swagger (has no defaults)
    • via swagger-routes function, mounting both the swagger-ui and swagger-docs and wiring them together
      • by default, mounts the swagger-ui to / and the swagger-spec to /swagger.json
    • via the old swagger-ui & swagger-docs (need to be separately imported from compojure.api.swagger).
    • see https://github.com/metosin/compojure-api/wiki/Swagger-integration for details

(defapi app
  (swagger-routes)
  (GET "/ping" []
    (ok {:message "pong"})))

(defapi app
  {:swagger {:ui "/", :spec "/swagger.json"}}
  (GET "/ping" []
    (ok {:message "pong"})))

• BREAKING: api-level coercion option is now a function of request => type => matcher as it is documented.
  Previously required a type => matcher map. Options are checked against type => matcher coercion input, and a
  descriptive error is thrown when api is created with the old options format.
• BREAKING: Renamed middlewares to middleware and :middlewares key (restructuring) to :middleware
  • will break at macro-expansion time with helpful exception
• BREAKING: Middleware must be defined as data: both middleware macro and :middleware restructuring
  take a vector of middleware containing either
  • a) fully configured middleware (function), or
  • b) a middleware templates in form of [function args]
  • You can also use anonymous or lambda functions to create middleware with correct parameters,
    these are all identical:
    • [[wrap-foo {:opts :bar}]]
    • [#(wrap-foo % {:opts :bar})]
    • [(fn [handler] (wrap-foo handler {:opts :bar}))]
  • Similar to duct
• BREAKING: (Custom restructuring handlers only) :parameters key used by restructure-param
  has been renamed to :swagger.
  • will break at macro-expansion time with helpful exception
• BREAKING public-resource-routes & public-resources are removed from compojure.api.middleware.
• BREAKING: compojure.api.legacy namespace has been removed.

Migration guide

https://github.com/metosin/compojure-api/wiki/Migration-Guide-to-1.0.0

Other stuff

• Additional route functions/macros in 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.
• top-level api is now just function, not a macro. It takes an optional options maps and a top-level route function.
• Coercer cache is now at api-level with 10000 entries.
• Code generated from restructured route macros is much cleaner now
• Coercion is on by default for standalone (apiless) endpoints.

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

• Removed deps:

[backtick "0.3.3"]

compare

• Swagger-routes mounted via api-options are mounted before other routes, fixes #218
• Routes are now resolved also from from Vars, fixes #219
• Better handling of :basePath with swagger-routes, thanks to Hoxu.
• Updated dependencies:

[metosin/ring-swagger "0.22.4"] is available but we use "0.22.3"

compare

• updated dependencies:

[prismatic/schema "1.0.5"] is available but we use "1.0.4"

compare

• Fixed path parameter handling in cases where path parameter is followed by an extension
  (#196, metosin/ring-swagger#82)
• Updated ring-swagger
• Added compojure.api.exception/with-logging helper to add logging to exception handlers.
  • Check extended wiki guide on exception handling
• Updated deps:

[metosin/ring-swagger "0.22.3"] is available

compare

• Updated ring-swagger
• Updated deps:

[metosin/ring-swagger "0.22.2"] is available
[metosin/ring-swagger-ui "2.1.4-0"] is available
[potemkin "0.4.3"] is available

compare

• coercer-cache is now per Route instead beeing global and based on a
  FIFO size 100 cache. Avoids potential memory leaks when using anonymous coercion matchers (which never hit the cache).
• Updated deps:

[prismatic/schema "1.0.4"] is available but we use "1.0.3"

compare

• Memoize coercers (for schema & matcher -input) for better performance.
  • Tests show 0-40% lower latency,
    depending on input & output schema complexity.
  • Tested by sending json-strings to api and reading json-string out.
  • Measured a 80% lower latency with a real world large Schema.
• Updated deps:

[potemkin "0.4.2"] is available but we use "0.4.1"

compare

• uses [Ring-Swagger "0.22.1"]
• clojure.tools.logging is used with default uncaugt exception handling if it's found
  on the classpath. Fixes #172.
• Both api and defapi produce identical swagger-docs. Fixes #159
• allow any swagger data to be overriden at runtime either via swagger-docs or via middlewares. Fixes #170.

[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"

compare

• BREAKING: Dropped support for Clojure 1.6
• BREAKING: Supports and depends on Schema 1.0.
• Uses upstream ring-middleware-format
  instead of Metosin fork.
• Uses now linked instead of
  ordered for maps where order matters.
• swagger-ui now supports passing arbitrary options to SwaggerUI
  (metosin/ring-swagger#67).
• Updated deps:

[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"

compare

• Routes are kept in order for swagger docs, Fixes #138.

compare

• Ring-swagger 0.21.0
  • BREAKING: new signature for dispatching custom JSON Schema transformations, old signature will break (nicely at compile-time), see Readme for details.
  • Support for collections in query parameters. E.g. :query-params [x :- [Long]] & url ?x=1&x=2&x=3 should result in x being [1 2 3].
• BREAKING: :validation-errors :error-handler, :validation-errors :catch-core-errors?
  and :exceptions :exception-handler options have been removed.
  • These have been replaced with general :exceptions :handlers options.
  • Fails nicely at compile-time
  • BREAKING: New handler use different arity than old handler functions.
    • new arguments: Exception, ex-info and request.
• Move context from compojure.api.sweet to compojure.api.legacy. Use context* instead.
• Updated deps:

[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"

compare

• fixes 150

compare

• fixes 137 & 134, thanks to @thomaswhitcomb!
• updated deps:

[metosin/ring-http-response "0.6.3"] is available but we use "0.6.2"
[midje "1.7.0"] is available but we use "1.7.0-SNAPSHOT"

compare

• Optional integration with Component.
  Use either :components-option of api-middleware or wrap-components-middleware
  to associate the components with your API. Then you can use :components-restructuring
  to destructure your components using letk syntax.
• fix for #123
• support for pluggable coercion, at both api-level & endpoint-level with option :coercion. See thethe tests.
  • coercion is a function of type - ring-request->coercion-type->coercion-matcher allowing protocol-based coercion in the future
    * BREAKING*: if you have created custom restructurings using src-coerce, they will break (nicely at compile-time)
• new restucturing :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"

• :multipart-params now sets :consumes ["multipart/form-data"] and :form-params sets
  :consumes ["application/x-www-form-urlencoded"]
• experimental: File upload support using compojure.api.upload namespace.

(POST* "/upload" []
  :multipart-params [file :- TempFileUpload]
  :middlewares [wrap-multipart-params]
  (ok (dissoc file :tempfile))))

• breaking: use plain Ring-Swagger 2.0 models with :responses. A helpful IllegalArgumentException will be thrown at compile-time with old models.
• new way:

:responses {400 {:schema ErrorSchema}}
:responses {400 {:schema ErrorSchema, :description "Eror"}}

• allow configuring of Ring-Swagger via api-middleware options with key :ring-swagger:

(defapi app
  {:ring-swagger {:ignore-missing-mappings? true}})
  (swagger-docs)
  (swagger-ui)
  ...)

• Bidirectinal routing, inspired by bidi - named routes & 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"}))))

• a validator for the api

(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

• updated dependencies:

[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"

• response descriptions can be given also with run-time meta-data (with-meta), fixes #96
  • in next MINOR version, we'll switch to (Ring-)Swagger 2.0 format.

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

• welcome compojure.api.core/api, the work-horse behind compojure.api.core/defapi.
• lexically bound route-trees, generated by api, pushed to request via ring-swagger middlewares.
  • no more +compojure-api-routes+ littering the handler namespaces.
• fixes #101
• fixes #102
• update dependencies:

[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"

• use ring-swagger middleware swagger-data injection instead of own custom mechanism.
• fixed #98: 2.0 UI works when running with context on (Servlet-based) app-servers.
• Preserve response-schema names, fixes #93.
• updated dependencies:

[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"

• New restructuring for :no-docs (a boolean) - endpoints with this don't get api documentation.
• Fixed #42 - defroutes* now does namespace resolution for the source
  used for route peeling and source linking (the macro magic)
• Fixed #91 - defroutes* are now automatically accessed over a Var for better development flow.
• Fixed #89.
• Fixed #82.
• Fixed #71, ring-swagger-ui
  is now a dependency.
• breaking ring.swagger.json-schema/describe is now imported into compojure.api.sweet for easy use. If your code
  refers to it directly, you need remove the direct reference.

Swagger 2.0 -support

Migration Guide

• Routes are collected always from the root (defapi or compojure.api.routes/api-root within that)
• compojure.api.routes/with-routes is now compojure.api.routes/api-root
• breaking requires the latest swagger-ui to work
  • [metosin/ring-swagger-ui "2.1.1-M2"] to get things pre-configured
  • or package 2.1.1-M2 yourself from the source.
• breaking: api ordering is not implemented.
• breaking: restructuring :nickname is now :operationId
• breaking: restructuring :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"}]})

• Swagger-documentation default uri is changed from /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
  ** in 2.0, apis are categorized by Tags, one can set them either to endpoints or to paths:

(GET* "/api/pets/" []
  :tags ["pet"]
  (ok ...))

(context* "/api/pets" []
  :tags ["pet"]
  (GET* "/" []
    :summary "get all pets"
    (ok ...)))

• updated deps:

[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"

• Fixed #79 by Jon Eisen
• updated deps:

[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"