reitit.openapi — fi.metosin/reitit-openapi 0.7.0-alpha1

create-openapi-handler clj/s

(create-openapi-handler)

Stability: alpha

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

openapi-feature clj/s

Stability: alpha

Feature for handling openapi-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 create-openapi-handler to expose the openapi spec.

New route data keys contributing to openapi docs:

key	description
:openapi	map of any openapi-data. Can contain keys like :deprecated.
:content-types	vector of supported content types. Defaults to ["application/json"]
:no-doc	optional boolean to exclude endpoint from api docs
:tags	optional set of string or keyword tags for an endpoint 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 openapi 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

Use :request parameter coercion (instead of :body) to unlock per-content-type coercions.

Example:

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

 ["/openapi.json"
  {:get {:no-doc true
         :openapi {:info {:title "my-api"}}
         :handler (reitit.openapi/create-openapi-handler)}}]

 ["/plus"
  {:get {:openapi {: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)})}}]]