reitit.openapi — metosin/reitit 0.7.0

-get-apidocs-openapi clj

(-get-apidocs-openapi coercion
                      {:keys [request muuntaja parameters responses
                              openapi/request-content-types
                              openapi/response-content-types]}
                      definitions)

create-openapi-handler clj

(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

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.
:openapi/request-content-types	vector of supported request content types. Defaults to ["application/json"] :response nnn :content :default. Only needed if you use the [:request :content :default] coercion.
:openapi/response-content-types	vector of supported response content types. Defaults to ["application/json"]. Only needed if you use the [:response nnn :content :default] coercion.
: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)})}}]]