Support for OpenAPI3

[ikitommi]

This spans over multiple repos, but can be done in parts.

Schema -> OpenAPI3

• Support OpenAPI3 schema-tools#44
• might be some work to get this clean without copying a lot

Spec -> OpenAPI3

• Support OpenAPI3 spec-tools#105
• should be easy, a new ns just like spec-tools.swagger overriding some JSON Schema parts (if any!)

Malli -> OpenAPI3

• https://github.com/metosin/reitit/blob/master/modules/reitit-malli/src/reitit/coercion/malli.cljc

Reitit Coercion

• currently, there is only one body-coercion for request and one for response. We should add support for content-type based coercion:

Coercion for all content-types

(require '[reitit.ring :as ring])
(require '[reitit.ring.coercion])
(require '[reitit.coercion.spec])
(require '[muuntaja.middleware])

(ring/ring-handler
  (ring/router
    ["/plus"
     {:get {:parameters {:body {:x int?, :y int?}}
            :responses {200 {:body {:total pos-int?}}}
            :handler (fn [{{{:keys [x y]} :body} :parameters}]
                       {:status 200, :body (+ x y)})}}]
    {:data {:middleware [muuntaja.middleware/wrap-format
                         reitit.ring.coercion/coerce-request-middleware
                         reitit.ring.coercion/coerce-response-middleware]
            :coercion reitit.coercion.spec/coercion}}))

Coercion per content-type

• new type :content (from OpenAPI3) which allows content-type->model mappings.
• should be disallowed with Swagger

(ring/ring-handler
  (ring/router
    ["/plus"
     {:get {:parameters {:content {"application/json" {:x neg-int?, :y neg-int?}
                                   "application/edn" {:x pos-int?, :y pos-int?}}}
            :responses {200 {:content {"application/json" {:json int?}
                                       "application/edn" {:edn int?}}}}
            :handler (fn [{{{:keys [x y]} :body} :parameters :as request}]
                       (let [content-type (-> request :muuntaja/response :format)
                             body (case content-type
                                    "application/json" {:json (+ x y)}
                                    "application/edn" {:edn (+ x y)})]
                         {:status 200, :body body}))}}]
    {:data {:middleware [muuntaja.middleware/wrap-format
                         reitit.ring.coercion/coerce-request-middleware
                         reitit.ring.coercion/coerce-response-middleware]
            :coercion reitit.coercion.spec/coercion}}))

... having both :body and :content could be allowed, the :body could be used as a default if the content-type doesn't match.

[ikitommi]

another option for the new key :content would be to reuse the :body key, but I think it would conflict with the string keys.

[valerauko]

There seem to be quite a lot of changes for OpenAPI 3.0. Would all of it need to be implemented here? https://swagger.io/blog/news/whats-new-in-openapi-3-0/

[ikitommi]

I think the core change is for the content-negotiation & better json-schema mappings. The rest (security &) are anyway left for client apps / libs to do as there are no existing helpers in reitit for those.

[ikitommi]

I think we could move the swagger parameter mapping from spec-tools and schema-tools into reitit-spec and reitit-schma modules. reitit-malli already does this: only the malli->JSON Schema mappings are in malli repo, and all the parameter handling is done here: https://github.com/metosin/reitit/blob/master/modules/reitit-malli/src/reitit/coercion/malli.cljc

Much easier to develop as it's all under one repo, open even opportunity to share code between the three impls.

[ikitommi]

Where to find the relevant (swagger2) code with malli:

• generate the apidocs: https://github.com/metosin/reitit/blob/master/modules/reitit-malli/src/reitit/coercion/malli.cljc#L140-L165
• swagger parameters: https://github.com/metosin/reitit/blob/master/modules/reitit-malli/src/reitit/coercion/malli.cljc#L82-L103

[czan]

In case it helps someone, until this issue is solved I created a hacky conversion from the existing reitit Swagger output to an OpenAPI spec. I first wrote it when I was using Spec coercion, but now I've moved to using Schema, so I'm not as confident about what gets generated from a Spec. I've been quite happy with my generated OpenAPI specs using this.

There are definitely gaps in functionality that I don't need/haven't run into yet, but it's something.

https://gist.github.com/czan/8752cacf527ceb0e64982b9fa8747892

[Koura]

In case it helps someone, until this issue is solved I created a hacky conversion from the existing reitit Swagger output to an OpenAPI spec. I first wrote it when I was using Spec coercion, but now I've moved to using Schema, so I'm not as confident about what gets generated from a Spec. I've been quite happy with my generated OpenAPI specs using this.

There are definitely gaps in functionality that I don't need/haven't run into yet, but it's something.

https://gist.github.com/czan/8752cacf527ceb0e64982b9fa8747892

I'm currently working on this issue and hopefully this can be closed soonish

[danielneal]

@Koura How far did you get with this?

[Koura]

@danielneal Sorry for the radio silence and slow progress. I haven't really been able to progress this for the last few months but should be able to continue now. Afaik support for schema and specs is already done but haven't yet been taken into use on reitit side. I have a WIP for the malli side of things

[sundbry]

Hi all, just jumping in here while trying to get my api integrated with some OpenAPI V3 tools. The gist from @czan works well. I recommend incorporating the following patch which helped me to get my /openapi.json validated.

66,69c65,68
<                 (assoc (dissoc endpoint :produces)
<                        :parameters non-body-parameters
<                        :requestBody fixed-body-parameter
<                        :responses fixed-responses)))
---
>                 (cond-> (dissoc endpoint :produces :consumes)
>                   non-body-parameters (assoc :parameters non-body-parameters)
>                   fixed-body-parameter (assoc :requestBody fixed-body-parameter)
>                   fixed-responses (assoc :responses fixed-responses))))

[hukka]

@Koura Swagger2 has annoying deficiencies like missing support for anyOf, so even a WIP would be interesting to see, and possibly to continue from.

[hukka]

OpenAPI 3.1 claims to be 100% compatible with JSONSchema, which already has support in, for example, Malli. Perhaps it would be feasible to skip 3.0 and go straight to the newest version, even if the ecosystem hasn't for most parts migrated to it (based on https://openapi.tools/).

[piotr-yuxuan]

+1 🙂

[piotr-yuxuan]

Thank you so much @ikitommi and @Koura for all the open-source marvels to which you've contributed! I'd really be interested in having the latest version of OpenAPI (3.0, 3.1, 3.x?) supported by malli. Off the top of my head here are the features of OpenAPI (3.x) that I miss in Swagger (2.0):

• Authentication schemes like bearer and OpenID (not related to reitit as @ikitommi mentionned above)
• Response links
• Different example values for different content mimetype

If somehow you had enough free brain time to dump a list of tasks yet to be completed so as to move toward all reitit coercions supporting OpenAPI, I think it might be helpful for the wider community to try and contribute – happy to look at it and see what I can do 🙂

[bowbahdoe]

This would be really cool for integration with stoplight - it takes swagger but its not happy with it

[jasonjckn]

+1 need this feature as well.

[grzm]

What's the current status of this work? I may be willing to throw some cycles at it. Having support for OpenApi 3.x would really be nice.

[PavlosMelissinos]

What's the current status of this work?

@grzm Afaik, there's this open PR that requires review.

I may be willing to throw some cycles at it.

Until metosin can review it, if you can spare some time I think it might be nice to test it in an actual project and report any problems (I've been meaning to do that for a while...).

[opqdonut]

FYI I'm working on this at metosin, trying to get all the various contributions glued together and adding the missing pieces.

[opqdonut]

Initial support for OpenAPI3 schemas is now in master and will be out in the next release.

Done:

• generating OpenAPI3 specs from malli, plumatic schema & spec schemas
• per-content-type coercions
• example: https://github.com/metosin/reitit/tree/master/examples/http-swagger
• docs: https://github.com/metosin/reitit/blob/master/doc/ring/openapi.md

TODO:

• support for multipart file upload OpenAPI3 multipart file upload support #591
• support for recursive schemas, see
  • Malli generates circular json-schema malli#868
  • openapi3 (mutual) recursion support #608
• refactoring and shuffling code around (e.g. moving some malli-related code to the malli repo)

[opqdonut]

One more thing: #605

[opqdonut]

OpenAPI3 support is now out in 0.7.0-alpha1. Blog post here: https://www.metosin.fi/blog/openapi3/