docs++

doc/SUMMARY.md

@@ -14,12 +14,6 @@
     * [Plumatic Schema](coercion/schema_coercion.md)
     * [Clojure.spec](coercion/clojure_spec_coercion.md)
     * [Data-specs](coercion/data_spec_coercion.md)
-* [Advanced](advanced/README.md)
-    * [Configuring Routers](advanced/configuring_routers.md)
-    * [Composing Routers](advanced/composing_routers.md)
-    * [Different Routers](advanced/different_routers.md)
-    * [Route Validation](advanced/route_validation.md)
-    * [Dev Workflow](advanced/dev_workflow.md)
 * [Ring](ring/README.md)
     * [Ring-router](ring/ring.md)
     * [Reverse-routing](ring/reverse_routing.md)
@@ -34,10 +28,18 @@
     * [Route Data Validation](ring/route_data_validation.md)
     * [Compiling Middleware](ring/compiling_middleware.md)
     * [Swagger Support](ring/swagger.md)
+* [Advanced](advanced/README.md)
+    * [Configuring Routers](advanced/configuring_routers.md)
+    * [Composing Routers](advanced/composing_routers.md)
+    * [Different Routers](advanced/different_routers.md)
+    * [Route Validation](advanced/route_validation.md)
+    * [Dev Workflow](advanced/dev_workflow.md)
+* [Patterns](patterns/README.md)
+    * [Shared Routes](patterns/shared_routes.md)
 * [Frontend](frontend/README.md)
     * [Basics](frontend/basics.md)
     * [Browser integration](frontend/browser.md)
-    * [Controllers](frontend/controllers.md)
+    * [Controllers (WIP)](frontend/controllers.md)
 * [Performance](performance.md)
 * [Interceptors (WIP)](interceptors.md)
 * [Development Instructions](development.md)

doc/cljdoc.edn

@@ -24,14 +24,6 @@
    ["Plumatic Schema" {:file "doc/coercion/schema_coercion.md"}]
    ["Clojure.spec" {:file "doc/coercion/clojure_spec_coercion.md"}]
    ["Data-specs" {:file "doc/coercion/data_spec_coercion.md"}]]
-  ["Advanced"
-   {:file "doc/advanced/README.md"}
-   ["Configuring Routers"
-    {:file "doc/advanced/configuring_routers.md"}]
-   ["Composing Routers" {:file "doc/advanced/composing_routers.md"}]
-   ["Different Routers" {:file "doc/advanced/different_routers.md"}]
-   ["Route Validation" {:file "doc/advanced/route_validation.md"}]
-   ["Dev Workflow" {:file "doc/advanced/dev_workflow.md"}]]
   ["Ring"
    {:file "doc/ring/README.md"}
    ["Ring-router" {:file "doc/ring/ring.md"}]
@@ -41,17 +33,31 @@
    ["Dynamic Extensions" {:file "doc/ring/dynamic_extensions.md"}]
    ["Data-driven Middleware"
     {:file "doc/ring/data_driven_middleware.md"}]
+   ["Transforming Middleware Chain"
+    {:file "doc/ring/transforming_middleware_chain.md"}]
    ["Middleware Registry" {:file "doc/ring/middleware_registry.md"}]
+   ["Default Middleware" {:file "doc/ring/default_middleware.md"}]
    ["Pluggable Coercion" {:file "doc/ring/coercion.md"}]
    ["Route Data Validation"
     {:file "doc/ring/route_data_validation.md"}]
    ["Compiling Middleware" {:file "doc/ring/compiling_middleware.md"}]
    ["Swagger Support" {:file "doc/ring/swagger.md"}]]
+  ["Advanced"
+   {:file "doc/advanced/README.md"}
+   ["Configuring Routers"
+    {:file "doc/advanced/configuring_routers.md"}]
+   ["Composing Routers" {:file "doc/advanced/composing_routers.md"}]
+   ["Different Routers" {:file "doc/advanced/different_routers.md"}]
+   ["Route Validation" {:file "doc/advanced/route_validation.md"}]
+   ["Dev Workflow" {:file "doc/advanced/dev_workflow.md"}]]
+  ["Patterns"
+   {:file "doc/patterns/README.md"}
+   ["Shared Routes" {:file "doc/patterns/shared_routes.md"}]]
   ["Frontend"
    {:file "doc/frontend/README.md"}
    ["Basics" {:file "doc/frontend/basics.md"}]
    ["Browser integration" {:file "doc/frontend/browser.md"}]
-   ["Controllers" {:file "doc/frontend/controllers.md"}]]
+   ["Controllers (WIP)" {:file "doc/frontend/controllers.md"}]]
   ["Performance" {:file "doc/performance.md"}]
   ["Interceptors (WIP)" {:file "doc/interceptors.md"}]
   ["Development Instructions" {:file "doc/development.md"}]

doc/frontend/README.md

@@ -2,4 +2,4 @@
 
 * [Basics](basics.md)
 * [Browser integration](browser.md)
-* [Controllers](controllers.md)
+* [Controllers (WIP)](controllers.md)

doc/frontend/basics.md

@@ -2,8 +2,6 @@
 
 * https://github.com/metosin/reitit/tree/master/examples/frontend
 
-**WIP**
-
 `reitit.frontend` provides few useful functions wrapping core functions:
 
 - `match-by-path` version which parses a URI using JavaScript, including

doc/frontend/browser.md

@@ -1,7 +1,5 @@
 # Frontend browser integration
 
-**WIP**
-
 Reitit includes two browser history integrations.
 
 Functions follow HTML5 History API: `push-state` to change route, `replace-state`

doc/frontend/controllers.md

@@ -1,6 +1,4 @@
-# Controllers
-
-**WIP**
+# Controllers (WIP)
 
 * https://github.com/metosin/reitit/tree/master/examples/frontend-controllers
 

doc/patterns/README.md

@@ -0,0 +1,3 @@
+# Patterns
+
+* [Shared Routes](shared_routes.md)

doc/patterns/shared_routes.md

@@ -0,0 +1,84 @@
+# Shared routes
+
+As `reitit-core` works with both Clojure & ClojureScript, one can have a shared routing table for both the frontend and the backend application, using the [Clujore Common Files](https://clojure.org/guides/reader_conditionals).
+
+For backend, you need to define a `:handler` for the request processing, for fronend, `:name` enables the use of [reverse routing](../basics/name_based_routing.md).
+
+There are multiple options to use shared routing table.
+
+## Using reader conditionals
+
+```clj
+;; define the handlers for for clojure
+#?(:clj (declare get-kikka))
+#?(:clj (declare post-kikka))
+
+;; :name for both, :handler just for clojure
+(def routes
+  ["/kikka"
+   {:name ::kikka
+    :get #?(:clj {:handler get-kikka})
+    :post #?(:clj {:handler post-kikka})}]
+```
+
+## Using custom expander
+
+raw-routes can have any non-sequential data as a route argument, which gets expanded using the `:expand` option given to the `reitit.core.router` function. It defaults to `reitit.core/expand` multimethod.
+
+First, define the common routes (in a `.cljc` file):
+
+```clj
+(def routes
+  [["/kikka" ::kikka]
+   ["/bar" ::bar]])
+```
+
+Those can be used as-is from ClojureScript:
+
+```clj
+(require '[reitit.core :as r])
+
+(def router
+  (r/router routes))
+
+(r/match-by-name router ::kikka)
+;#Match{:template "/kikka"
+;       :data {:name :user/kikka}
+;       :result nil
+;       :path-params nil
+;       :path "/kikka"}
+```
+
+For the backend, we can use a custom-expander to expand the routes:
+
+```clj
+(require '[reitit.ring :as ring])
+
+(defn my-expand [registry]
+  (fn [data opts]
+    (or (if (keyword? data)
+          (some-> data
+                  registry
+                  (r/expand opts)
+                  (assoc :name data)))
+        (r/expand data opts))))
+
+;; the handler functions
+(defn get-kikka [_] {:status 200, :body "get"})
+(defn post-kikka [_] {:status 200, :body "post"})
+(defn bar [_] {:status 200, :body "bar"})
+
+(def app
+  (ring/ring-handler
+    (ring/router
+      [["/kikka" ::kikka]
+       ["/bar" ::bar]]
+      ;; use a custom expander
+      {:expand (my-expand
+                 {::kikka {:get get-kikka
+                           :post post-kikka}
+                  ::bar bar})})))
+
+(app {:request-method :post, :uri "/kikka"})
+; {:status 200, :body "post"}
+```

examples/ring-swagger/src/example/server.clj

@@ -75,7 +75,9 @@
                            ;; multipart
                            multipart/multipart-middleware]}})
     (ring/routes
-      (swagger-ui/create-swagger-ui-handler {:path "/"})
+      (swagger-ui/create-swagger-ui-handler
+        {:path "/"
+         :config {:validatorUrl nil})
       (ring/create-default-handler))))
 
 (defn start []