Support for multiple examples in OpenAPI

[vengroff]

This is a feature request originally posted in #57 (comment).

I have an OpenAPI spec that has a post endpoint with an examples section contained within the content section of the requestBody. When I look at the doc generated from this with the default zudoku.config.ts there is a box on the right where I can see sample calls in curl or a variety of languages. But all of them just pass empty lists or dictionaries to the various components of the request. All fields empty is not a valid input for this API, so it is frustrating to users that they don't see a working example.

What I would like to do is have a drop-down listing each of the examples the API spec provides with text for each choice coming from the summary field of one of the examples. When I pick one I would like to have it fill in the values in the example code from the value component of the chosen example and also render the description from the description field so the user can read it. This gives the user a known working input that they can then copy and paste or modify as they see fit. The standard docs generated by FastAPI do this for the API spec in question.

[linear]

ZUP-4012 Support examples from the OpenAPI Spec

[vengroff]

Looking forward to this. Is there a way to get some additional visibility on priority and timing? I'm guessing that's what the linear bot link above is about, but it isn't visible to me.

[mosch]

hey @vengroff, looking at the current behavior I agree I think is broken.
We've been discussing the right thing to do here a couple of times.

From my testing it looks like the defined example doesn't make it into the documentation at all. Do you experience the same?

[mosch]

We have a fix for showing the exmaples, should be available in a new version soon: #533

Update: It doesn't support choosing the examples yet, we still need to handle this feature request.

[vengroff]

Thank you. Supporting example at the argument level is great. examples is what I was most looking for. So that way if there are specific combinations of arguments that illustrate certain use cases we can put them all in the examples section and have them available from a drop-down with their descriptions.

The extension of this is to take the metadata in examples for whichever entry the user has selected from the drop down and generate sample calls across a variety of client languages, which the user also picks from another drop down.

[mosch]

Makes sense, we discussed the implementation of this today and we plan to add this feature soon. Thank you for asking about this again.