Liking cljdoc? Tell your friends :D

reitit.swagger


create-swagger-handler

(create-swagger-handler)
source

swagger-feature

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:

keydescription
:swaggermap of any swagger-data. Must have :id (keyword or sequence of keywords) to identify the api
:no-docoptional boolean to exclude endpoint from api docs
:tagsoptional set of strings of keywords tags for an endpoint api docs
:summaryoptional short string summary of an endpoint
:descriptionoptional long description of an endpoint. Supports http://spec.commonmark.org/

Also the coercion keys contribute to swagger spec:

keydescription
:parametersoptional input parameters for a route, in a format defined by the coercion
:responsesoptional 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 {: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)})}}]]
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
| :tags         | optional set of strings of keywords 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 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 {: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)})}}]]
sourceraw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close