Allow setting examples for the parameters

[royteeuwen]

It would be very handy to be able to set examples for the parameters / request body. At this moment when importing the generated open api in for example Postman, it sets the values to "non ipsum pariatur"

[kbuntrock]

Hello,

Thanks you for your issue.

This is something I'm thinking about for a long time.
I'm planning several ways of doing it (probably not all implemented for the same release).

First of all, my goal with this plugin is to not force to modify the code / add dependencies just for the sake of documentation. Multiple examples on an API can take a lot of space.

I was thinking to allow to register some yaml files where the examples will be registered with the operation id of the endpoint.
While creating the documentation, if the plugin find one or several matching examples, it will enrich the generated documentation with it.
I'm thinking also about:

• one example file = one java controller
• auto-creating them if configured like so (and eventually also creating dummy examples)
• alerting if an example does not match any operation.

Second option could be the use of extra javadoc tags to add examples to the operation. Examples would be in the javadoc and the plugin with the help of theses specific tags would know it has to be integrated as example.
Down point: I can never try to generate a "dummy" example with this method as I do not want to alter the original source code.

Last option is to support swagger annotations. But I just want to allow this method to smooth a migration from another plugin to this one. Since get rid of the annotation overhead was one of the ideas behind this project, I do not want to encourage their use. It will be probably be one of the last solution I will implement.

Do you have any suggestions about these strategies?

I'm currently traveling to some random locations and I might take some days between my answers.

Kind regards,
Kevin

[royteeuwen]

Hey Kévin,

Thanks for the thorough info! I didn't know that this was the strategy of the plugin, namely not updating the source code itself. I do get that this might be an issue for some cases, but for all the cases I have had so far where I want to auto-generate an Open API spec, it was because they were in my control. This means that I can also easily add an annotation here and there.

The nice thing about using the annotations is that it forces you to keep the code and the docs in sync, while if you have some free-text yaml somewhere, you won't even see that there are yaml's linked and / or update them. This doesn't mean that both situations could be supported I guess ;).

Greets,
Roy