diff --git a/doc/SUMMARY.md b/doc/SUMMARY.md
index adf4fb29..153a6bd0 100644
--- a/doc/SUMMARY.md
+++ b/doc/SUMMARY.md
@@ -18,7 +18,6 @@
     * [Configuring Routers](advanced/configuring_routers.md)
     * [Different Routers](advanced/different_routers.md)
     * [Route Validation](advanced/route_validation.md)
-    * [Interceptors](advanced/interceptors.md)
 * [Ring](ring/README.md)
     * [Ring-router](ring/ring.md)
     * [Dynamic Extensions](ring/dynamic_extensions.md)
@@ -26,6 +25,7 @@
     * [Pluggable Coercion](ring/coercion.md)
     * [Route Data Validation](ring/route_data_validation.md)
     * [Compiling Middleware](ring/compiling_middleware.md)
+* [Interceptors](interceptors.md)
+* [Swagger & Openapi](openapi.md)
 * [Performance](performance.md)
 * [FAQ](faq.md)
-* TODO: Swagger & OpenAPI
diff --git a/doc/advanced/README.md b/doc/advanced/README.md
index 3bb47889..cad41444 100644
--- a/doc/advanced/README.md
+++ b/doc/advanced/README.md
@@ -3,4 +3,3 @@
 * [Configuring Routers](configuring_routers.md)
 * [Different Routers](different_routers.md)
 * [Route Validation](route_validation.md)
-* [Interceptors](interceptors.md)
diff --git a/doc/advanced/interceptors.md b/doc/advanced/interceptors.md
deleted file mode 100644
index 441fed49..00000000
--- a/doc/advanced/interceptors.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Interceptors
-
-Reitit also supports [Pedestal](pedestal.io)-style [interceptors](http://pedestal.io/reference/interceptors).
-
-## work in progress
-
-* port the (coericon) middleware into interceptors
-* separate Clojure(Script) runner?
-* Docs
-* Samples
-
diff --git a/doc/interceptors.md b/doc/interceptors.md
new file mode 100644
index 00000000..86ae43cb
--- /dev/null
+++ b/doc/interceptors.md
@@ -0,0 +1,58 @@
+# Interceptors
+
+Reitit also supports [Pedestal](pedestal.io)-style [interceptors](http://pedestal.io/reference/interceptors) via `reitit.interceptor` package.
+
+Full support is WIP at the moment:
+
+* separate module (or library?) for interceptor interpreters
+* figure out how to make a truly portable Interceptor definitions, e.g. Pedestal has namespaced keys for context errors, queues etc.
+* finalize `reitit-http` module as an alternative to `reitit-ring`
+
+Current `reitit-http` draft (with data-specs):
+
+```clj
+(require '[reitit.http.coercion :as rhc])
+(require '[reitit.http :as http])
+(require '[reitit.coercion.spec])
+(require '[clojure.set :as set])
+
+(def auth-interceptor
+  "Interceptor that mounts itself if route has `:roles` data. Expects `:roles`
+  to be a set of keyword and the context to have `[:user :roles]` with user roles.
+  responds with HTTP 403 if user doesn't have the roles defined, otherwise no-op."
+  {:name ::auth
+   :compile (fn [{:keys [roles]} _]
+              (if (seq roles)
+                {:description (str "requires roles " roles)
+                 :spec {:roles #{keyword?}}
+                 :context-spec {:user {:roles #{keyword}}}
+                 :enter (fn [{{user-roles :roles} :user :as ctx}]
+                          (if (not (set/subset? roles user-roles))
+                            (assoc ctx :response {:status 403, :body "forbidden"})
+                            ctx))}))})(require '[clojure.set :as set])
+
+(def app
+  (http/http-handler
+    (http/router
+      ["/api" {:interceptors [auth-interceptor]}
+       ["/ping" {:name ::ping
+                 :get (constantly
+                        {:status 200
+                         :body "pong"})}]
+       ["/plus/:z" {:name ::plus
+                    :post {:parameters {:query {:x int?}
+                                        :body {:y int?}
+                                        :path {:z int?}}
+                           :responses {200 {:body {:total pos-int?}}}
+                           :roles #{:admin}
+                           :handler (fn [{:keys [parameters]}]
+                                      (let [total (+ (-> parameters :query :x)
+                                                     (-> parameters :body :y)
+                                                     (-> parameters :path :z))]
+                                        {:status 200
+                                         :body {:total total}}))}}]]
+      {:data {:coercion reitit.coercion.spec/coercion
+              :interceptors [rhc/coerce-exceptions-interceptor
+                             rhc/coerce-request-interceptor
+                             rhc/coerce-response-interceptor]}})))
+```
diff --git a/doc/openapi.md b/doc/openapi.md
new file mode 100644
index 00000000..fc5c43b9
--- /dev/null
+++ b/doc/openapi.md
@@ -0,0 +1,11 @@
+# Swagger & OpenAPI
+
+Goal is to support both [Swagger](https://swagger.io/) & [OpenAPI](https://www.openapis.org/) specifications for route documentation.
+
+Swagge-support draft works, but only for Clojure.
+
+TODO:
+
+* [metosin/schema-tools#38](https://github.com/metosin/schema-tools/issues/38): extract Schema-swagger from [ring-swagger](https://github.com/metosin/ring-swagger) into [schema-tools](https://github.com/metosin/schema-tools) to support both Clojure & ClojureScript
+* separate modules for the swagger2 & openapi
+* [metosin/spec-tools#105](https://github.com/metosin/spec-tools/issues/105): support OpenApi