Middleware that just defines extra keys that can be present in a route data, with zero runtime penalty:

(def swagger-middleware
  "Middleware for handling swagger-documentation for routes.
  Does not participate in request processing, just provides new
  valid keys for the route data:

  Swagger-spesific keys:

  | key           | description |
  | --------------|-------------|
  | ::name        | keyword name for the swagger-api set.
  | ::info        | swagger info map

  The following common route keys also contribute to swagger spec:

  | key           | description |
  | --------------|-------------|
  | :summary      | optional short string summary of an endpoint
  | :description  | optional long description of an endpoint. Supports 
  | :parameters   | optional input parameters for a route, in a format defined by the coercion
  | :responses    | optional descriptions of responess, in a format defined by coercion
  | :no-doc       | optional boolean to exclude endpoint from api docs
  | :tags         | optional set of strings of keywords tags for an endpoint api docs

  Example:

      [\"/api\"
       {::swagger/name :my-api
        :middleware [swagger/swagger-middleware]}

       [\"/swagger.json\"
        {:no-doc true
         ::swagger/info {:title \"my-api\"}
         :handler swagger-spec-handler}]

       [\"/plus\"
        {:get {:tags #{:math}
               :summary \"adds numbers together\"
               :description \"takes `x` and `y` query-params and adds them together\"
               :parameters {:query {:x int?, :y int?}}
               :responses {200 {:body {:total int?}}}
               :handler ...}}]]"
  {:name ::swagger
   :spec ::swagger})

Also the proposed api to add swagger-docs to routes. Comments most welcome!