metosin/reitit

Move OpenAPI 3 request coercions outside `:parameters`

opqdonut opened this issue · 3 comments

opqdonut commented

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/
opqdonut commented

Previously: #84

ikitommi commented

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

opqdonut commented

I think all of this is done now!