luciano/reitit
1
0
Fork 0
mirror of https://github.com/metosin/reitit.git synced 2026-01-30 01:30:34 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: update openapi & coercion docs

Browse source
This commit is contained in:
Joel Kaasinen 2023-08-28 15:41:16 +03:00
parent c6541de1b5
commit 38547e4ad2
2 changed files with 45 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
doc/ring/coercion.md
View file

@ -152,7 +152,10 @@ Invalid response:
## Per-content-type coercion ## Per-content-type coercion
You can also specify request and response body schemas per content-type. The syntax for this is: You can also specify request and response body schemas per
content-type. These are also read by the [OpenAPI
feature](./openapi.md) when generating api docs. The syntax for this
is:
```clj ```clj
(def app (def app
@ -161,13 +164,12 @@ You can also specify request and response body schemas per content-type. The syn
["/api" ["/api"
["/example" {:post {:coercion reitit.coercion.schema/coercion ["/example" {:post {:coercion reitit.coercion.schema/coercion
:request {:content {"application/json" {:schema {:y s/Int}} :request {:content {"application/json" {:schema {:y s/Int}}
"application/edn" {:schema {:z s/Int}}} "application/edn" {:schema {:z s/Int}}
;; default if no content-type matches: ;; default if no content-type matches:
:body {:yy s/Int}} :default {:schema {:yy s/Int}}}}
:responses {200 {:content {"application/json" {:schema {:w s/Int}} :responses {200 {:content {"application/json" {:schema {:w s/Int}}
"application/edn" {:schema {:x s/Int}}} "application/edn" {:schema {:x s/Int}}
;; default if no content-type matches: :default {:schema {:ww s/Int}}}}}
:body {:ww s/Int}}}
:handler ...}}]] :handler ...}}]]
{:data {:middleware [rrc/coerce-exceptions-middleware {:data {:middleware [rrc/coerce-exceptions-middleware
rrc/coerce-request-middleware rrc/coerce-request-middleware

55
doc/ring/openapi.md
View file

@ -30,10 +30,9 @@ Coercion keys also contribute to the docs:
| key | description | | key | description |
| --------------|-------------| | --------------|-------------|
| :parameters | optional input parameters for a route, in a format defined by the coercion | :parameters | optional input parameters for a route, in a format defined by the coercion
| :request | optional description of body parameters, possibly per content-type
| :responses | optional descriptions of responses, in a format defined by coercion | :responses | optional descriptions of responses, in a format defined by coercion
Use `:request` parameter coercion (instead of `:body`) to unlock per-content-type coercions. See [Coercion](coercion.md).
## Annotating schemas ## Annotating schemas
You can use malli properties, schema-tools data or spec-tools data to You can use malli properties, schema-tools data or spec-tools data to
@ -81,28 +80,46 @@ Spec:
:y int?}}}}}] :y int?}}}}}]
``` ```
## Per-content-type coercions
Use `:request` coercion (instead of `:body`) to unlock
per-content-type coercions. This also lets you specify multiple named
examples. See [Coercion](coercion.md) for more info. See also [the
openapi example](../../examples/openapi).
```clj
["/pizza"
{:get {:summary "Fetch a pizza | Multiple content-types, multiple examples"
:content-types ["application/json" "application/edn"]
:responses {200 {:content {"application/json" {:description "Fetch a pizza as json"
:schema [:map
[:color :keyword]
[:pineapple :boolean]]
:examples {:white {:description "White pizza with pineapple"
:value {:color :white
:pineapple true}}
:red {:description "Red pizza"
:value {:color :red
:pineapple false}}}}
"application/edn" {:description "Fetch a pizza as edn"
:schema [:map
[:color :keyword]
[:pineapple :boolean]]
:examples {:red {:description "Red pizza with pineapple"
:value (pr-str {:color :red :pineapple true})}}}}}}
```
## Custom OpenAPI data ## Custom OpenAPI data
The `:openapi` route data key can be used to add top-level or The `:openapi` route data key can be used to add top-level or
route-level information to the generated OpenAPI spec. This is useful route-level information to the generated OpenAPI spec. This is useful
for providing `"securitySchemes"`, `"examples"` or other OpenAPI keys for providing `"securitySchemes"` or other OpenAPI keys that are not
that are not generated automatically by reitit. generated automatically by reitit.
```clj See [the openapi example](../../examples/openapi) for a working
["/foo" example of `"securitySchemes"`.
{:post {:parameters {:body {:name string? :age int?}}
:openapi {:requestBody
{:content
{"application/json"
{:examples {"Pyry" {:summary "Pyry, 45y"
:value {:name "Pyry" :age 45}}
"Cat" {:summary "Cat, 8y"
:value {:name "Cat" :age 8}}}}}}}
...}}]
```
See [the ring-malli-swagger example](../../examples/ring-malli-swagger) for
working examples of `"securitySchemes"` and `"examples"`.
## OpenAPI spec ## OpenAPI spec