Fork me on GitHub
Slack Archive

This page is not created by, affiliated with, or supported by Slack Technologies, Inc.

2023-03-29

Channels

#reitit
<
2023-03-29
>
joshuamz19:03:22

Hello everyone. First of all thanks for creating an amazing library. Lately, I've been trying to define an API to great detail with Reitit, Malli Coercion and Swagger (with Swagger UI) and been following closely your process supporting OpenAPI 3 (https://github.com/metosin/reitit/issues/84 and particularly https://github.com/metosin/reitit/issues/84#issuecomment-1469499583) Question is, are there any plans to support multiple examples, a feature only available to OAI3? (https://swagger.io/docs/specification/adding-examples/, notice the mentions to multiple examples). In my particular case, I need to design an API with very few endpoints but with very complex payloads. So we consider having different examples for the same endpoint would be great to test right away in the UI. Attached you'll find a screenshot of Swagger UI when the examples keyword is present under requestBody.content.<content-type>, along with the schema keyword. I tried to accomplish something similar to that with Reitit and Malli but my examples node (coming from a :json-schema/examples property in the request body Malli schema) went under requestBody.content.<content-type>.schema , which doesn't work. Also I tried to read through the latest additions to the reitit.coercion.malli ns and found that -get-apidocs-openapi, at its most nested maps, uses just {:schema schema} (https://github.com/metosin/reitit/blob/2a3e382df1a4b6a50ed9a7a1ca6e048f4247336f/modules/reitit-malli/src/reitit/coercion/malli.cljc#L165) Thanks for all the effort! Happy to help wherever possible.

opqdonut06:03:58

Oh, cool, thanks for pointing that out. I hadn't realised we need additional support for examples.

opqdonut06:03:45

Would you prefer specifying the examples on the reitit level or in the malli specs?

opqdonut06:03:41

On the reitit level I'm imagining something like 

{:request {:content {"application/json" {:schema Foo
                                         :examples {"Foo1" ... "Foo2" ...}}}}}

👍 2
opqdonut06:03:29

and on the malli level it would be a property like :openapi/examples

opqdonut06:03:24

it's kind of a weird feature since the individual "example" fields are allowed anhywhere inside the json-schema, but the multiple examples are allowed only on the request/response level

jasonjckn04:04:06

> Would you prefer specifying the examples on the reitit level or in the malli specs? personally I would prefer malli schema support

joshuamz16:04:05

@US1LTFF6D Thank you for looking into this and sorry for the late response. Hmm maybe I'd like to add examples at the route level because those might actually come from loaded fixtures, or just pointers to things hosted somewhere else (see https://swagger.io/docs/specification/adding-examples/#external). I know we can do the same directly in the Malli schema properties, but wouldn't that make :json-schema/examples like a special property that needs special handling, compared to other :json-schema/* keywords? In the end, I don't have a hard opinion on either approach. However, there are other properties that might need to be supported in the content type map generated: example (singular, outside the schema object) and encoding which might be useful in some cases (described https://swagger.io/docs/specification/describing-request-body/ and spec'ed https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-12).