From 45f4f2cf403c5b28f09bd8b8a2005aa4747f3edc Mon Sep 17 00:00:00 2001 From: Wanderson Ferreira Date: Wed, 15 Jan 2020 13:05:03 -0300 Subject: [PATCH 1/2] format negotiation documentation to reitit --- doc/advanced/format_negotiation.md | 73 ++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 doc/advanced/format_negotiation.md diff --git a/doc/advanced/format_negotiation.md b/doc/advanced/format_negotiation.md new file mode 100644 index 00000000..39334efb --- /dev/null +++ b/doc/advanced/format_negotiation.md @@ -0,0 +1,73 @@ +# Format Negotiation + +`reitit` uses [muuntaja](https://github.com/metosin/muuntaja) as a library to handle format negotiation, encoding and decoding. + +In order to have access to the options below, you need the following namespaces: + +```clj +(require '[muuntaja.core :as m]) +``` + +Then, a `muuntaja` instance must be installed in the router to your coercion benefit from the customizations. + +```clj +(ring/ring-handler + (ring/router + ;; your route definitions + ;; .... + :data {:coercion reitit.coercion.spec/coercion + :muuntaja m/instance}}) +``` + + +## Changing default parameters + +The current JSON formatter used by `reitit` already have the option to parse keys as `keyword` which is a sane default in Clojure. However, if you would like to parse all the `double` as `bigdecimal` you'd need to change an option of the [JSON formatter](https://github.com/metosin/jsonista) + + +```clj +(def new-muuntaja-instance + (m/create + (assoc-in + m/default-options + [:formats "application/json" :decoder-opts :bigdecimals] + true))) + +``` + +Now you should change the `m/instance` installed in the router with the `new-muuntaja-instance`. + +You can find more options for [JSON](https://cljdoc.org/d/metosin/jsonista/0.2.5/api/jsonista.core#object-mapper) and [EDN]. + + +## Adding custom encoder + +The example below is from `muuntaja` explaining how to add a custom encoder to parse a `java.util.Date` instance. + +```clj + +(def muuntaja-instance + (m/create + (assoc-in + m/default-options + [:formats "application/json" :encoder-opts] + {:date-format "yyyy-MM-dd"}))) + +(->> {:value (java.util.Date.)} + (m/encode m "application/json") + slurp) +; => "{\"value\":\"2019-10-15\"}" + +``` + +## Adding all together + +If you inspect `m/default-options` it's only a map, therefore you can compose your new muuntaja instance with as many options as you need it. + +```clj +(def new-muuntaja + (m/create + (-> m/default-options + (assoc-in [:formats "application/json" :decoder-opts :bigdecimals] true) + (assoc-in [:formats "application/json" :encoder-opts :data-format] "yyyy-MM-dd")))) +``` From fbe2f625765259e3b9ec0448395c4349cb134cdf Mon Sep 17 00:00:00 2001 From: Wanderson Ferreira Date: Thu, 16 Jan 2020 22:50:27 -0300 Subject: [PATCH 2/2] split default_middleware and merge more options to content negotiation --- doc/SUMMARY.md | 1 + doc/advanced/format_negotiation.md | 73 --------------- doc/ring/content_negotiation.md | 138 +++++++++++++++++++++++++++++ doc/ring/default_middleware.md | 85 ------------------ 4 files changed, 139 insertions(+), 158 deletions(-) delete mode 100644 doc/advanced/format_negotiation.md create mode 100644 doc/ring/content_negotiation.md diff --git a/doc/SUMMARY.md b/doc/SUMMARY.md index 9e3f9e65..111f0ccf 100644 --- a/doc/SUMMARY.md +++ b/doc/SUMMARY.md @@ -34,6 +34,7 @@ * [Transforming Middleware Chain](ring/transforming_middleware_chain.md) * [Middleware Registry](ring/middleware_registry.md) * [Default Middleware](ring/default_middleware.md) +* [Content Negotiation](ring/content_negotiation.md) * [Ring Coercion](ring/coercion.md) * [Route Data Validation](ring/route_data_validation.md) * [Compiling Middleware](ring/compiling_middleware.md) diff --git a/doc/advanced/format_negotiation.md b/doc/advanced/format_negotiation.md deleted file mode 100644 index 39334efb..00000000 --- a/doc/advanced/format_negotiation.md +++ /dev/null @@ -1,73 +0,0 @@ -# Format Negotiation - -`reitit` uses [muuntaja](https://github.com/metosin/muuntaja) as a library to handle format negotiation, encoding and decoding. - -In order to have access to the options below, you need the following namespaces: - -```clj -(require '[muuntaja.core :as m]) -``` - -Then, a `muuntaja` instance must be installed in the router to your coercion benefit from the customizations. - -```clj -(ring/ring-handler - (ring/router - ;; your route definitions - ;; .... - :data {:coercion reitit.coercion.spec/coercion - :muuntaja m/instance}}) -``` - - -## Changing default parameters - -The current JSON formatter used by `reitit` already have the option to parse keys as `keyword` which is a sane default in Clojure. However, if you would like to parse all the `double` as `bigdecimal` you'd need to change an option of the [JSON formatter](https://github.com/metosin/jsonista) - - -```clj -(def new-muuntaja-instance - (m/create - (assoc-in - m/default-options - [:formats "application/json" :decoder-opts :bigdecimals] - true))) - -``` - -Now you should change the `m/instance` installed in the router with the `new-muuntaja-instance`. - -You can find more options for [JSON](https://cljdoc.org/d/metosin/jsonista/0.2.5/api/jsonista.core#object-mapper) and [EDN]. - - -## Adding custom encoder - -The example below is from `muuntaja` explaining how to add a custom encoder to parse a `java.util.Date` instance. - -```clj - -(def muuntaja-instance - (m/create - (assoc-in - m/default-options - [:formats "application/json" :encoder-opts] - {:date-format "yyyy-MM-dd"}))) - -(->> {:value (java.util.Date.)} - (m/encode m "application/json") - slurp) -; => "{\"value\":\"2019-10-15\"}" - -``` - -## Adding all together - -If you inspect `m/default-options` it's only a map, therefore you can compose your new muuntaja instance with as many options as you need it. - -```clj -(def new-muuntaja - (m/create - (-> m/default-options - (assoc-in [:formats "application/json" :decoder-opts :bigdecimals] true) - (assoc-in [:formats "application/json" :encoder-opts :data-format] "yyyy-MM-dd")))) -``` diff --git a/doc/ring/content_negotiation.md b/doc/ring/content_negotiation.md new file mode 100644 index 00000000..90605ad7 --- /dev/null +++ b/doc/ring/content_negotiation.md @@ -0,0 +1,138 @@ +# Content Negotiation + +Wrapper for [Muuntaja](https://github.com/metosin/muuntaja) middleware for content-negotiation, request decoding and response encoding. Takes explicit configuration via `:muuntaja` key in route data. Emit's [swagger](swagger.md) `:produces` and `:consumes` definitions automatically based on the Muuntaja configuration. + +Negotiates a request body based on `Content-Type` header and response body based on `Accept`, `Accept-Charset` headers. Publishes the negotiation results as `:muuntaja/request` and `:muuntaja/response` keys into the request. + +Decodes the request body into `:body-params` using the `:muuntaja/request` key in request if the `:body-params` doesn't already exist. + +Encodes the response body using the `:muuntaja/response` key in request if the response doesn't have `Content-Type` header already set. + +Expected route data: + +| key | description | +| -------------|-------------| +| `:muuntaja` | `muuntaja.core/Muuntaja` instance, does not mount if not set. + +```clj +(require '[reitit.ring.middleware.muuntaja :as muuntaja]) +``` + +* `muuntaja/format-middleware` - Negotiation, request decoding and response encoding in a single Middleware +* `muuntaja/format-negotiate-middleware` - Negotiation +* `muuntaja/format-request-middleware` - Request decoding +* `muuntaja/format-response-middleware` - Response encoding + +```clj +(require '[reitit.ring :as ring]) +(require '[reitit.ring.coercion :as rrc]) +(require '[reitit.coercion.spec :as rcs]) +(require '[ring.adapter.jetty :as jetty]) +(require '[muuntaja.core :as m]) + +(def app + (ring/ring-handler + (ring/router + [["/math" + {:post {:summary "negotiated request & response (json, edn, transit)" + :parameters {:body {:x int?, :y int?}} + :responses {200 {:body {:total int?}}} + :handler (fn [{{{:keys [x y]} :body} :parameters}] + {:status 200 + :body {:total (+ x y)}})}}] + ["/xml" + {:get {:summary "forced xml response" + :handler (fn [_] + {:status 200 + :headers {"Content-Type" "text/xml"} + :body "kukka"})}}]] + {:data {:muuntaja m/instance + :coercion rcs/coercion + :middleware [muuntaja/format-middleware + rrc/coerce-exceptions-middleware + rrc/coerce-request-middleware + rrc/coerce-response-middleware]}}))) + +(jetty/run-jetty #'app {:port 3000, :join? false}) +``` + +Testing with [httpie](https://httpie.org/): + +```bash +> http POST :3000/math x:=1 y:=2 + +HTTP/1.1 200 OK +Content-Length: 11 +Content-Type: application/json; charset=utf-8 +Date: Wed, 22 Aug 2018 16:59:54 GMT +Server: Jetty(9.2.21.v20170120) + +{ + "total": 3 +} +``` + +```bash +> http :3000/xml + +HTTP/1.1 200 OK +Content-Length: 20 +Content-Type: text/xml +Date: Wed, 22 Aug 2018 16:59:58 GMT +Server: Jetty(9.2.21.v20170120) + +kukka +``` + + +## Changing default parameters + +The current JSON formatter used by `reitit` already have the option to parse keys as `keyword` which is a sane default in Clojure. However, if you would like to parse all the `double` as `bigdecimal` you'd need to change an option of the [JSON formatter](https://github.com/metosin/jsonista) + + +```clj +(def new-muuntaja-instance + (m/create + (assoc-in + m/default-options + [:formats "application/json" :decoder-opts :bigdecimals] + true))) + +``` + +Now you should change the `m/instance` installed in the router with the `new-muuntaja-instance`. + +You can find more options for [JSON](https://cljdoc.org/d/metosin/jsonista/0.2.5/api/jsonista.core#object-mapper) and [EDN]. + + +## Adding custom encoder + +The example below is from `muuntaja` explaining how to add a custom encoder to parse a `java.util.Date` instance. + +```clj + +(def muuntaja-instance + (m/create + (assoc-in + m/default-options + [:formats "application/json" :encoder-opts] + {:date-format "yyyy-MM-dd"}))) + +(->> {:value (java.util.Date.)} + (m/encode m "application/json") + slurp) +; => "{\"value\":\"2019-10-15\"}" + +``` + +## Adding all together + +If you inspect `m/default-options` it's only a map, therefore you can compose your new muuntaja instance with as many options as you need it. + +```clj +(def new-muuntaja + (m/create + (-> m/default-options + (assoc-in [:formats "application/json" :decoder-opts :bigdecimals] true) + (assoc-in [:formats "application/json" :encoder-opts :data-format] "yyyy-MM-dd")))) +``` diff --git a/doc/ring/default_middleware.md b/doc/ring/default_middleware.md index cac98fc1..9de3bede 100644 --- a/doc/ring/default_middleware.md +++ b/doc/ring/default_middleware.md @@ -23,91 +23,6 @@ Any Ring middleware can be used with `reitit-ring`, but using data-driven middle See [Exception Handling with Ring](exceptions.md). -## Content Negotiation - -Wrapper for [Muuntaja](https://github.com/metosin/muuntaja) middleware for content-negotiation, request decoding and response encoding. Takes explicit configuration via `:muuntaja` key in route data. Emit's [swagger](swagger.md) `:produces` and `:consumes` definitions automatically based on the Muuntaja configuration. - -Negotiates a request body based on `Content-Type` header and response body based on `Accept`, `Accept-Charset` headers. Publishes the negotiation results as `:muuntaja/request` and `:muuntaja/response` keys into the request. - -Decodes the request body into `:body-params` using the `:muuntaja/request` key in request if the `:body-params` doesn't already exist. - -Encodes the response body using the `:muuntaja/response` key in request if the response doesn't have `Content-Type` header already set. - -Expected route data: - -| key | description | -| -------------|-------------| -| `:muuntaja` | `muuntaja.core/Muuntaja` instance, does not mount if not set. - -```clj -(require '[reitit.ring.middleware.muuntaja :as muuntaja]) -``` - -* `muuntaja/format-middleware` - Negotiation, request decoding and response encoding in a single Middleware -* `muuntaja/format-negotiate-middleware` - Negotiation -* `muuntaja/format-request-middleware` - Request decoding -* `muuntaja/format-response-middleware` - Response encoding - -```clj -(require '[reitit.ring :as ring]) -(require '[reitit.ring.coercion :as rrc]) -(require '[reitit.coercion.spec :as rcs]) -(require '[ring.adapter.jetty :as jetty]) - -(def app - (ring/ring-handler - (ring/router - [["/math" - {:post {:summary "negotiated request & response (json, edn, transit)" - :parameters {:body {:x int?, :y int?}} - :responses {200 {:body {:total int?}}} - :handler (fn [{{{:keys [x y]} :body} :parameters}] - {:status 200 - :body {:total (+ x y)}})}}] - ["/xml" - {:get {:summary "forced xml response" - :handler (fn [_] - {:status 200 - :headers {"Content-Type" "text/xml"} - :body "kukka"})}}]] - {:data {:muuntaja m/instance - :coercion rcs/coercion - :middleware [muuntaja/format-middleware - rrc/coerce-exceptions-middleware - rrc/coerce-request-middleware - rrc/coerce-response-middleware]}}))) - -(jetty/run-jetty #'app {:port 3000, :join? false}) -``` - -Testing with [httpie](https://httpie.org/): - -```bash -> http POST :3000/math x:=1 y:=2 - -HTTP/1.1 200 OK -Content-Length: 11 -Content-Type: application/json; charset=utf-8 -Date: Wed, 22 Aug 2018 16:59:54 GMT -Server: Jetty(9.2.21.v20170120) - -{ - "total": 3 -} -``` - -```bash -> http :3000/xml - -HTTP/1.1 200 OK -Content-Length: 20 -Content-Type: text/xml -Date: Wed, 22 Aug 2018 16:59:58 GMT -Server: Jetty(9.2.21.v20170120) - -kukka -``` - ## Multipart Request Handling Wrapper for [Ring Multipart Middleware](https://github.com/ring-clojure/ring/blob/master/ring-core/src/ring/middleware/multipart_params.clj). Emits swagger `:consumes` definitions automatically.