mirror of
https://github.com/metosin/reitit.git
synced 2025-12-16 16:01:11 +00:00
Enchance docs
This commit is contained in:
Tommi Reiman
parent
f524459768
commit
998656a9ac
4 changed files with 82 additions and 70 deletions
70
CHANGELOG.md
70
CHANGELOG.md
|
|
@ -1,14 +1,14 @@
|
|||
## UNRELEASED
|
||||
|
||||
## `reitit-core`
|
||||
### `reitit-core`
|
||||
|
||||
* `segment-router` doesn't accept empty segments as path-parameters, fixes [#181](https://github.com/metosin/reitit/issues/181).
|
||||
* path-params are decoded correctly with `r/match-by-name`, fixes [#192](https://github.com/metosin/reitit/issues/192).
|
||||
* new `:quarantine-router`, which is uses by default if there are any path conflicts: uses internally `:mixed-router` for non-conflicting routes and `:linear-router` for conflicting routes.
|
||||
|
||||
```clj
|
||||
(-> [["/joulu/kinkku"] ;; linear router
|
||||
["/joulu/:torttu"] ;; linear router
|
||||
(-> [["/joulu/kinkku"] ;; linear-router
|
||||
["/joulu/:torttu"] ;; linear-router
|
||||
["/tonttu/:id"] ;; segment-router
|
||||
["/manna/puuro"] ;; lookup-router
|
||||
["/sinappi/silli"]] ;; lookup-router
|
||||
|
|
@ -17,7 +17,13 @@
|
|||
; => :quarantine-router
|
||||
```
|
||||
|
||||
* updated deps:
|
||||
### `reitit-pedestal`
|
||||
|
||||
* new optional module for [Pedestal](http://pedestal.io/) integration. See [the docs](https://metosin.github.io/reitit/http/pedestal.html).
|
||||
|
||||
### dependencies
|
||||
|
||||
* updated:
|
||||
|
||||
```clj
|
||||
[metosin/muuntaja "0.6.3"] is available but we use "0.6.1"
|
||||
|
|
@ -25,17 +31,17 @@
|
|||
|
||||
## 0.2.9 (2018-11-21)
|
||||
|
||||
## `reitit-spec`
|
||||
### `reitit-spec`
|
||||
|
||||
* support for vector data-specs for request & response parameters by [Heikki Hämäläinen](https://github.com/hjhamala).
|
||||
|
||||
## 0.2.8 (2018-11-18)
|
||||
|
||||
## `reitit-core`
|
||||
### `reitit-core`
|
||||
|
||||
* Added support for composing middleware & interceptor transformations, fixes [#167](https://github.com/metosin/reitit/issues/167).
|
||||
|
||||
## `reitit-spec`
|
||||
### `reitit-spec`
|
||||
|
||||
* Spec problems are exposed as-is into request & response coercion errors, enabling pretty-printers like [expound](https://github.com/bhb/expound) to be used:
|
||||
|
||||
|
|
@ -81,13 +87,13 @@
|
|||
:query-params {"x" "1", "y" "-2"}})
|
||||
```
|
||||
|
||||
## `reitit-swagger`
|
||||
### `reitit-swagger`
|
||||
|
||||
* `create-swagger-handler` support now 3-arity ring-async, thanks to [Miloslav Nenadál](https://github.com/nenadalm)
|
||||
|
||||
## 0.2.7 (2018-11-11)
|
||||
|
||||
## `reitit-spec`
|
||||
### `reitit-spec`
|
||||
|
||||
* Fixes [spec coercion issue with aliased specs](https://github.com/metosin/spec-tools/issues/145)
|
||||
|
||||
|
|
@ -99,12 +105,12 @@
|
|||
|
||||
## 0.2.6 (2018-11-09)
|
||||
|
||||
## `reitit-core`
|
||||
### `reitit-core`
|
||||
|
||||
* Faster path-parameter decoding: doing less work when parameters don't need decoding. Wildcard-routing is now 10-15% faster in perf tests (opensensors & github api).
|
||||
* Fixed a ClojureScript compiler warning about private var usage. [#169](https://github.com/metosin/reitit/issues/169)
|
||||
|
||||
## `reitit-ring`
|
||||
### `reitit-ring`
|
||||
|
||||
* `redirect-trailing-slash-handler` can strip multiple slashes from end of the uri, by [Hannu Hartikainen](https://github.com/dancek).
|
||||
* Fixed a ClojureScript compiler warning about `satisfies?` being a macro.
|
||||
|
|
@ -115,7 +121,7 @@
|
|||
[ring "1.7.1"] is available but we use "1.7.0"
|
||||
```
|
||||
|
||||
## `reitit-spec`
|
||||
### `reitit-spec`
|
||||
|
||||
* updated deps:
|
||||
|
||||
|
|
@ -123,7 +129,7 @@
|
|||
[metosin/spec-tools "0.8.1"] is available but we use "0.8.0"
|
||||
```
|
||||
|
||||
## `reitit-schema`
|
||||
### `reitit-schema`
|
||||
|
||||
* updated deps:
|
||||
|
||||
|
|
@ -131,7 +137,7 @@
|
|||
[metosin/schema-tools "0.10.5"] is available but we use "0.10.4"
|
||||
```
|
||||
|
||||
## `reitit-sieppari`
|
||||
### `reitit-sieppari`
|
||||
|
||||
* updated deps:
|
||||
|
||||
|
|
@ -141,7 +147,7 @@
|
|||
|
||||
## 0.2.5 (2018-10-30)
|
||||
|
||||
## `reitit-ring`
|
||||
### `reitit-ring`
|
||||
|
||||
* router is injected into request also in the default branch
|
||||
* new `reitit.ring/redirect-trailing-slash-handler` to [handle trailing slashes](https://metosin.github.io/reitit/ring/slash_handler.html) with style!
|
||||
|
|
@ -170,17 +176,17 @@
|
|||
[ring/ring-core "1.7.1"] is available but we use "1.7.0"
|
||||
```
|
||||
|
||||
## `reitit-http`
|
||||
### `reitit-http`
|
||||
|
||||
* router is injected into request also in the default branch
|
||||
|
||||
## 0.2.4 (2018-10-21)
|
||||
|
||||
## `reitit-ring`
|
||||
### `reitit-ring`
|
||||
|
||||
* New option `:not-found-handler` in `reitit.ring/create-resource-handler` to set how 404 is handled. Fixes [#89](https://github.com/metosin/reitit/issues/89), thanks to [valerauko](https://github.com/valerauko).
|
||||
|
||||
## `reitit-spec`
|
||||
### `reitit-spec`
|
||||
|
||||
* Latest features from [spec-tools](https://github.com/metosin/spec-tools)
|
||||
* Swagger enchancements
|
||||
|
|
@ -195,7 +201,7 @@
|
|||
|
||||
## 0.2.3 (2018-09-24)
|
||||
|
||||
## `reitit-ring`
|
||||
### `reitit-ring`
|
||||
|
||||
* `ring-handler` takes optionally a 3rd argument, an options map which can be used to se top-level middleware, applied before any routing is done:
|
||||
|
||||
|
|
@ -236,13 +242,13 @@
|
|||
[ring/ring-core "1.7.0"] is available but we use "1.6.3"
|
||||
```
|
||||
|
||||
## `reitit-http`
|
||||
### `reitit-http`
|
||||
|
||||
* `:options` requests are served for all routes by default with 200 OK to better support things like [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)
|
||||
* the default handler is not documented in Swagger
|
||||
* new router option `:reitit.http/default-options-handler` to change this behavior. Setting `nil` disables this.
|
||||
|
||||
## `reitit-middleware`
|
||||
### `reitit-middleware`
|
||||
|
||||
* fix `reitit.ring.middleware.parameters/parameters-middleware`
|
||||
|
||||
|
|
@ -252,7 +258,7 @@
|
|||
[metosin/muuntaja "0.6.1"] is available but we use "0.6.0"
|
||||
```
|
||||
|
||||
## `reitit-swagger-ui`
|
||||
### `reitit-swagger-ui`
|
||||
|
||||
* updated deps:
|
||||
|
||||
|
|
@ -267,17 +273,17 @@
|
|||
* [Sieppari, reitit-http & swagger](https://github.com/metosin/reitit/blob/master/examples/http-swagger/src/example/server.clj)
|
||||
* [Pedestal, reitit-http & swagger](https://github.com/metosin/reitit/blob/master/examples/pedestal-swagger/src/example/server.clj)
|
||||
|
||||
## `reitit-middleware`
|
||||
### `reitit-middleware`
|
||||
|
||||
* new middleware `reitit.ring.middleware.parameters/parameters-middleware` to wrap query & form params.
|
||||
|
||||
## `reitit-interceptors`
|
||||
### `reitit-interceptors`
|
||||
|
||||
* new module like `reitit-middleware` but for interceptors. See the [Docs](https://metosin.github.io/reitit/http/default_interceptors.html).
|
||||
|
||||
## 0.2.1 (2018-09-04)
|
||||
|
||||
## `reitit-schema`
|
||||
### `reitit-schema`
|
||||
|
||||
* updated deps:
|
||||
|
||||
|
|
@ -285,7 +291,7 @@
|
|||
[metosin/schema-tools "0.10.4"] is available but we use "0.10.3"
|
||||
```
|
||||
|
||||
## `reitit-middleware`
|
||||
### `reitit-middleware`
|
||||
|
||||
* updated deps:
|
||||
|
||||
|
|
@ -303,7 +309,7 @@ Sample apps demonstraing the current status of `reitit`:
|
|||
* [`reitit-http` with Pedestal](https://github.com/metosin/reitit/blob/master/examples/pedestal/src/example/server.clj)
|
||||
* [`reitit-http` with Sieppari](https://github.com/metosin/reitit/blob/master/examples/http/src/example/server.clj)
|
||||
|
||||
## `reitit-core`
|
||||
### `reitit-core`
|
||||
|
||||
* **BREAKING**: the router option key to extract body format has been renamed: `:extract-request-format` => `:reitit.coercion/extract-request-format`
|
||||
* should only concern you if you are not using [Muuntaja](https://github.com/metosin/muuntaja).
|
||||
|
|
@ -355,7 +361,7 @@ Sample apps demonstraing the current status of `reitit`:
|
|||
; {:status 200, :body {:bonus 30}}
|
||||
```
|
||||
|
||||
## `reitit-swagger`
|
||||
### `reitit-swagger`
|
||||
|
||||
* In case of just one swagger api per router, the swagger api doesn't have to identified, so this works now:
|
||||
|
||||
|
|
@ -374,12 +380,12 @@ Sample apps demonstraing the current status of `reitit`:
|
|||
(swagger-ui/create-swagger-ui-handler {:path "/"}))
|
||||
```
|
||||
|
||||
## `reitit-middleware`
|
||||
### `reitit-middleware`
|
||||
|
||||
* A new module with common data-driven middleware: exception handling, content negotiation & multipart requests. See [the docs](https://metosin.github.io/reitit/ring/default_middleware.html).
|
||||
|
||||
|
||||
## `reitit-swagger-ui`
|
||||
### `reitit-swagger-ui`
|
||||
|
||||
* **BREAKING**: pass swagger-ui `:config` as-is (instead of mixed-casing keys) to swagger-ui, fixes [#109](https://github.com/metosin/reitit/issues/109):
|
||||
* see [docs](https://github.com/swagger-api/swagger-ui/tree/2.x#parameters) for available parameters.
|
||||
|
|
@ -392,13 +398,13 @@ Sample apps demonstraing the current status of `reitit`:
|
|||
:validatorUrl nil}})
|
||||
```
|
||||
|
||||
## `reitit-frontend`
|
||||
### `reitit-frontend`
|
||||
|
||||
* new module for frontend-routing. See [docs](https://metosin.github.io/reitit/frontend/basics.html) for details.
|
||||
|
||||
## 0.1.3 (2018-6-25)
|
||||
|
||||
## `reitit-core`
|
||||
### `reitit-core`
|
||||
|
||||
* `reitit.coercion/coerce!` coerced all parameters found in match, e.g. injecting in `:query-parameters` into `Match` with coerce those too if `:query` coercion is defined.
|
||||
* if response coercion is not defined for a response status, response is still returned
|
||||
|
|
|
|||
|
|
@ -1,12 +1,23 @@
|
|||
# Pedestal
|
||||
|
||||
[Pedestal](http://pedestal.io/) is a well known interceptor-based web framework for Clojure. To use `reitit-http` with Pedestal, we need to change the default routing interceptor. The needed helpers for this are found in a separate package:
|
||||
[Pedestal](http://pedestal.io/) is a backend web framework for Clojure. `reitit-pedestal` provides an alternative routing engine for Pedestal.
|
||||
|
||||
```clj
|
||||
[metosin/reitit-ring "0.2.9"]
|
||||
[metosin/reitit-pedestal "0.2.9"]
|
||||
```
|
||||
|
||||
You should read the [interceptor guide](interceptors.md) to understand the basics on Interceptor-based dispatch.
|
||||
Why should one use reitit instead of the Pedestal [default routing](http://pedestal.io/reference/routing-quick-reference)?
|
||||
|
||||
* One simple [route syntax](../basics/route_syntax.md), with full [route conflict resolution](../basics/route_conflicts.md).
|
||||
* Supports [first class route data](../basics/route_data.md) with [spec validation](../basics/route_data_validation.md).
|
||||
* Fixes some [known problems](https://github.com/pedestal/pedestal/issues/532) in routing.
|
||||
* Can handle [trailing backslashes](../ring/slash_handler.md).
|
||||
* One router for both backend and [frontend](../frontend/basics.md).
|
||||
* Supports [parameter coercion](../ring/coercion.md) & [Swagger](../ring/swagger.md).
|
||||
* Is even [faster](../performance.md).
|
||||
|
||||
To use Pedestal with reitit, you should first read both the [Pedestal docs](http://pedestal.io/) and the [reitit interceptor guide](interceptors.md).
|
||||
|
||||
|
||||
## Example
|
||||
|
||||
|
|
@ -24,47 +35,38 @@ A minimalistic example on how to to swap the default-router with a reitit router
|
|||
[reitit.http :as http]
|
||||
[reitit.ring :as ring]))
|
||||
|
||||
(def router
|
||||
(pedestal/routing-interceptor
|
||||
(http/router
|
||||
["/ping" (fn [_] {:status 200, :body "pong"})])
|
||||
(ring/create-default-handler)))
|
||||
(def routes
|
||||
["/ping" {:get (fn [_] {:status 200, :body "pong"})}])
|
||||
|
||||
(defn start []
|
||||
(-> {::server/type :jetty
|
||||
::server/port 3000
|
||||
::server/join? false
|
||||
;; no pedestal routes
|
||||
::server/routes []}
|
||||
(server/default-interceptors)
|
||||
;; swap the reitit router
|
||||
(pedestal/replace-last-interceptor router)
|
||||
(server/dev-interceptors)
|
||||
(server/create-server)
|
||||
(server/start))
|
||||
(println "server running in port 3000"))
|
||||
|
||||
(start)
|
||||
(-> {::server/type :jetty
|
||||
::server/port 3000
|
||||
::server/join? false
|
||||
;; no pedestal routes
|
||||
::server/routes []}
|
||||
(server/default-interceptors)
|
||||
;; swap the reitit router
|
||||
(pedestal/replace-last-interceptor
|
||||
(pedestal/routing-interceptor
|
||||
(http/router routes)))
|
||||
(server/dev-interceptors)
|
||||
(server/create-server)
|
||||
(server/start))
|
||||
```
|
||||
|
||||
## Caveat
|
||||
## Compatibility
|
||||
|
||||
There is no common interceptor spec for Clojure and All default reitit interceptors (coercion, exceptions etc.) use the [Sieppari](https://github.com/metosin/sieppari) interceptor model. For most parts, they are fully compatible with the Pedestal Interceptor model. Only exception being that the `:error` handlers take just 1 arity (`context`) compared to [Pedestal's 2-arity](http://pedestal.io/reference/error-handling) (`context` and `exception`).
|
||||
There is no common interceptor spec for Clojure and all default reitit interceptors (coercion, exceptions etc.) use the [Sieppari](https://github.com/metosin/sieppari) interceptor model. It is mostly compatible with the Pedestal Interceptor model, only exception being that the `:error` handlers take just 1 arity (`context`) compared to [Pedestal's 2-arity](http://pedestal.io/reference/error-handling) (`context` and `exception`).
|
||||
|
||||
Currently, there is only the `reitit.http.interceptors.exception/exception-interceptor` which has `:error` defined - just don't use it and everything should just work.
|
||||
Currently, out of the reitit default interceptors, there is only the `reitit.http.interceptors.exception/exception-interceptor` which has the `:error` defined.
|
||||
|
||||
You are most welcome to discuss about a common interceptor spec in [#interceptors](https://clojurians.slack.com/messages/interceptors/) in [Clojurians Slack](http://clojurians.net/).
|
||||
|
||||
See the [error handling guide](http://pedestal.io/reference/error-handling) on how to handle errors with Pedestal.
|
||||
You are most welcome to discuss about a common interceptor spec in [#interceptors](https://clojurians.slack.com/messages/interceptors/) on [Clojurians Slack](http://clojurians.net/).
|
||||
|
||||
## More examples
|
||||
|
||||
### Simple
|
||||
|
||||
Simple example, with both sync & async interceptors: https://github.com/metosin/reitit/tree/master/examples/pedestal
|
||||
Simple example with sync & async interceptors: https://github.com/metosin/reitit/tree/master/examples/pedestal
|
||||
|
||||
### Swagger
|
||||
|
||||
More complete example with custom interceptors, [default interceptors](default_interceptors.md), [coercion](../coercion/coercion.md) and [swagger](../ring/swagger.md)-support: https://github.com/metosin/reitit/tree/master/examples/pedestal-swagger
|
||||
|
||||
note: exception handling is disabled in this example
|
||||
More complete example with custom interceptors, [default interceptors](default_interceptors.md), [coercion](../coercion/coercion.md) and [swagger](../ring/swagger.md)-support enabled: https://github.com/metosin/reitit/tree/master/examples/pedestal-swagger
|
||||
|
|
|
|||
|
|
@ -8,4 +8,5 @@
|
|||
:plugins [[lein-parent "0.3.2"]]
|
||||
:parent-project {:path "../../project.clj"
|
||||
:inherit [:deploy-repositories :managed-dependencies]}
|
||||
:dependencies [[metosin/reitit-http]])
|
||||
:dependencies [[io.pedestal/pedestal.service]
|
||||
[metosin/reitit-http]])
|
||||
|
|
|
|||
11
project.clj
11
project.clj
|
|
@ -23,15 +23,18 @@
|
|||
[metosin/reitit-frontend "0.2.9"]
|
||||
[metosin/reitit-sieppari "0.2.9"]
|
||||
[metosin/reitit-pedestal "0.2.9"]
|
||||
[meta-merge "1.0.0"]
|
||||
[lambdaisland/deep-diff "0.0-25"]
|
||||
[ring/ring-core "1.7.1"]
|
||||
[metosin/ring-swagger-ui "2.2.10"]
|
||||
[metosin/spec-tools "0.8.2"]
|
||||
[metosin/schema-tools "0.10.5"]
|
||||
[metosin/muuntaja "0.6.3"]
|
||||
[metosin/jsonista "0.2.2"]
|
||||
[metosin/sieppari "0.0.0-alpha6"]]
|
||||
[metosin/sieppari "0.0.0-alpha6"]
|
||||
|
||||
[meta-merge "1.0.0"]
|
||||
[lambdaisland/deep-diff "0.0-25"]
|
||||
[ring/ring-core "1.7.1"]
|
||||
|
||||
[io.pedestal/pedestal.service "0.5.5"]]
|
||||
|
||||
:plugins [[jonase/eastwood "0.3.4"]
|
||||
[lein-doo "0.1.11"]
|
||||
|
|
|
|||
Loading…
Reference in a new issue