Support for Swagger/OpenAPI

[ikitommi]

Proposal:

• metosin/reitit-swagger (and metosin/reitit-openapi) module
• :responses and :parameters data is read from coercion
• other keys: :no-docs (disable docs), :swagger (any swagger-data)
• swagger-middleware that doesn't participate in request processing but provides specs for the new keys for route data validation
• swagger-spec-handler that produces the swagger-spec
• [:swagger :id] defines the api(docs). All routes with the same id are part of the apidcs
  • enables multiple apidocs per routing tree. Value can be keyword or set of keyword
  • enables route to be part of multiple api-docs

Draft with data-specs:

(require '[reitit.ring :as ring])
(require '[reitit.ring.swagger :as swagger])
(require '[reitit.ring.coercion :as rrc])
(require '[reitit.coercion.spec :as spec])

(def app
  (ring/ring-handler
    (ring/router
      ["/api"
       ;; identify a swagger api
       ;; there can be several in a routing tree
       {:swagger {:id :math}}

       ;; the (undocumented) swagger spec endpoint
       ["/swagger.json"
        {:get {:no-doc true
               :swagger {:info {:title "my-api"}}
               :handler swagger/swagger-spec-handler}}]

       ["/minus"
        {:get {:summary "minus"
               :parameters {:query {:x int?, :y int?}}
               :responses {200 {:body {:total int?}}}
               :handler (fn [{{{:keys [x y]} :query} :parameters}]
                          {:status 200, :body {:total (- x y)}})}}]

       ["/plus"
        {:get {:summary "plus"
               :parameters {:query {:x int?, :y int?}}
               :responses {200 {:body {:total int?}}}
               :handler (fn [{{{:keys [x y]} :query} :parameters}]
                          {:status 200, :body {:total (+ x y)}})}}]]

      {:data {:middleware [;; does not particiate in request processing
                           ;; just defines specs for the extra keys
                           swagger/swagger-middleware
                           rrc/coerce-exceptions-middleware
                           rrc/coerce-request-middleware
                           rrc/coerce-response-middleware]
              :coercion spec/coercion}})))

[ikitommi]

Works with spec (clj + cljs), Schema is wip.

(require '[reitit.ring :as ring])
(require '[reitit.swagger :as swagger])
(require '[reitit.ring.coercion :as rrc])
(require '[reitit.coercion.spec :as spec])
(require '[reitit.coercion.schema :as schema])

(require '[schema.core :refer [Int]])
(require '[muuntaja.middleware])

(ring/ring-handler
  (ring/router
    ["/api"
     {:swagger {:id ::math}}

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

     ["/spec" {:coercion spec/coercion}
      ["/plus"
       {:get {:summary "plus"
              :parameters {:query {:x int?, :y int?}}
              :responses {200 {:body {:total int?}}}
              :handler (fn [{{{:keys [x y]} :query} :parameters}]
                         {:status 200, :body {:total (+ x y)}})}}]]

     ["/schema" {:coercion schema/coercion}
      ["/plus"
       {:get {:summary "plus"
              :parameters {:query {:x Int, :y Int}}
              :responses {200 {:body {:total Int}}}
              :handler (fn [{{{:keys [x y]} :query} :parameters}]
                         {:status 200, :body {:total (+ x y)}})}}]]]

    {:data {:middleware [muuntaja.middleware/wrap-format
                         swagger/swagger-feature
                         rrc/coerce-exceptions-middleware
                         rrc/coerce-request-middleware
                         rrc/coerce-response-middleware]}}))

[ikitommi]

Schema is done too, all SNAPSHOTS.

[ikitommi]

Ultimate Swagger guide at https://metosin.github.io/reitit/ring/swagger.html