doc: update openapi & coercion docs

metosin · Aug 28, 2023 · 38547e4 · 38547e4
1 parent c6541de
commit 38547e4
Show file tree

Hide file tree

Showing 2 changed files with 45 additions and 26 deletions.
diff --git a/doc/ring/coercion.md b/doc/ring/coercion.md
@@ -152,7 +152,10 @@ Invalid response:
 
 ## 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
 (def app
@@ -161,13 +164,12 @@ You can also specify request and response body schemas per content-type. The syn
     ["/api"
      ["/example" {:post {:coercion reitit.coercion.schema/coercion
                          :request {:content {"application/json" {:schema {:y s/Int}}
-                                             "application/edn" {:schema {:z s/Int}}}
-                                   ;; default if no content-type matches:
-                                   :body {:yy s/Int}}
+                                             "application/edn" {:schema {:z s/Int}}
+                                             ;; default if no content-type matches:
+                                             :default {:schema {:yy s/Int}}}}
                          :responses {200 {:content {"application/json" {:schema {:w s/Int}}
-                                                    "application/edn" {:schema {:x s/Int}}}
-                                          ;; default if no content-type matches:
-                                          :body {:ww s/Int}}}
+                                                    "application/edn" {:schema {:x s/Int}}
+                                                    :default {:schema {:ww s/Int}}}}}
                          :handler ...}}]]
     {:data {:middleware [rrc/coerce-exceptions-middleware
                          rrc/coerce-request-middleware

diff --git a/doc/ring/openapi.md b/doc/ring/openapi.md
@@ -30,10 +30,9 @@ Coercion keys also contribute to the docs:
 | key           | description |
 | --------------|-------------|
 | :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
 
-Use `:request` parameter coercion (instead of `:body`) to unlock per-content-type coercions. See [Coercion](coercion.md).
-
 ## Annotating schemas
 
 You can use malli properties, schema-tools data or spec-tools data to
@@ -81,28 +80,46 @@ Spec:
                                       :y int?}}}}}]
 ```
 
-## Custom OpenAPI data
+## Per-content-type coercions
 
-The `:openapi` route data key can be used to add top-level or
-route-level information to the generated OpenAPI spec. This is useful
-for providing `"securitySchemes"`, `"examples"` or other OpenAPI keys
-that are not generated automatically by reitit.
+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
-["/foo"
- {: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}}}}}}}
-         ...}}]
+["/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})}}}}}}
 ```
 
-See [the ring-malli-swagger example](../../examples/ring-malli-swagger) for
-working examples of `"securitySchemes"` and `"examples"`.
+
+
+## Custom OpenAPI data
+
+The `:openapi` route data key can be used to add top-level or
+route-level information to the generated OpenAPI spec. This is useful
+for providing `"securitySchemes"` or other OpenAPI keys that are not
+generated automatically by reitit.
+
+See [the openapi example](../../examples/openapi) for a working
+example of `"securitySchemes"`.
 
 ## OpenAPI spec