Move OpenAPI 3 request coercions outside `:parameters`

[Joel Kaasinen]

Currently

• Mix of :body and :schema
• Defaults on different level of nesting compared to per-content-type stuff
• Can't add per-content-type extra fields like :examples

["/foo" {:post {:parameters {:request {:content {"application/json" <schema>}
                                       :body <schema>}
                             ;; OR
                             :body <schema>}
                :responses {200 {:description ...
                                 :content {"application/json" {:schema <schema>}}
                                 :body <schema>}}}}]

New format

["/foo" {:post {:request {:description ...
                          :content {"application/json" {:schema <schema>
                                                        :examples ...}
                                    :default {:schema <schema>}}}
                :parameters {:body <schema>}   ;; still supported for backwards compatibility & simple use cases
                :responses {200 {:description ...
                                 :content {"application/json" {:schema <schema>
                                                               :examples ...}
                                           :default {:schema <schema>}}
                                 :body <schema>}}}] ;; still supported for backwards compatibility?

Benefits:

• More symmetry between :request and :responses
• Can give OpenAPI3 multiple examples directly, without resorting to :openapi
• Future-proofing:
  • could support per-content-type :handlers

TODO

• implementation
  • use new format in coercions
  • use new format when generating openapi
  • warnings if using new format with swagger
• rewrite openapi_test.clj to use new format
• update examples:
  • http-swagger
  • ring-malli-swagger
  • ring-spec-swagger
• update openapi.md
• update coercion.md
• update ring/coercion.md
• update Metosin blog post: https://www.metosin.fi/blog/openapi3/

[Joel Kaasinen]

Previously: #84

[Tommi Reiman]

initial implementation (ignore whitespace to see the diff better): https://github.com/metosin/reitit/pull/628/files?w=1

[Joel Kaasinen]

I think all of this is done now!