reitit.swagger — metosin/reitit 0.5.8

create-swagger-handler clj/s

(create-swagger-handler)

Create a ring handler to emit swagger spec. Collects all routes from router which have an intersecting [:swagger :id] and which are not marked with :no-doc route data.

swagger-feature clj/s

Feature for handling swagger-documentation for routes. Works both with Middleware & Interceptors. Does not participate in actual request processing, just provides specs for the new documentation keys for the route data. Should be accompanied by a [[swagger-spec-handler]] to expose the swagger spec.

New route data keys contributing to swagger docs:

key	description
:swagger	map of any swagger-data. Must have :id (keyword or sequence of keywords) to identify the api
:no-doc	optional boolean to exclude endpoint from api docs
:summary	optional short string summary of an endpoint
:description	optional long description of an endpoint. Supports http://spec.commonmark.org/

Also the coercion keys contribute to swagger spec:

key	description
:parameters	optional input parameters for a route, in a format defined by the coercion
:responses	optional descriptions of responses, in a format defined by coercion

Example:

["/api"
 {:swagger {:id :my-api}
  :middleware [reitit.swagger/swagger-feature]}

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

 ["/plus"
  {:get {:swagger {: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 pos-int?}}}
         :handler (fn [{:keys [parameters]}]
                    {:status 200
                     :body (+ (-> parameters :query :x)
                              (-> parameters :query :y)})}}]]