Be able to allow the user to use only `Response` on return type

[mcruzdev]

The idea is to allow the user to configure the codegen to add as return type only Response.

Actually the rule to get the right return type is made on: https://github.com/Apicurio/apicurio-codegen/blob/ab67ddaf48d598548be0d411a8de13ec333cc0c3/core/src/main/java/io/apicurio/hub/api/codegen/OpenApi2JaxRs.java#L678 method.

Maybe to give a new configuration to the final user would be great. WDYT @EricWittmann ?

Originally created here quarkiverse/quarkus-openapi-generator#835

[EricWittmann]

I'm going to blow your mind. We already have this feature:

https://github.com/Apicurio/apicurio-codegen/blob/main/core/src/test/resources/OpenApi2JaxRsTest/custom-response-type.json#L64

There are actually a bunch of vendor extensions that can be used to customize the output of the generator. This is one of them.

Do we need something more than this, do you think?

[mcruzdev]

Nice! I didn't really see that, I knew about the extensions but I didn't go into depth.

I think we can go with this approach, the idea is to give something global, to avoid the need to edit/add the entire OpenAPI specification.

About all extensions, where I can put documentation about it, this one already exists?

[EricWittmann]

Yeah documentation basically does not exist for this project at the moment. :( I'm open to ideas on this topic! My default would be to start with markdown in the GH repository in a /docs directory, and link to it from the README (which I will update so it's not empty). wdyt?

[EricWittmann]

Regarding making the option global - there is a vendor extension supported at the root of the OpenAPI document that contains a number of more global config settings. We could allow this extension to live in there. Then when we look for x-codegen-returnType we can check for it as we do now but also check the root (local setting would override the root setting). Thoughts?

[mcruzdev]

It makes sense, could I follow this approach and send a pull request?

[EricWittmann]

Yes please. :)

[diegostalder]

where do i find a documentation/reference of this generator options ?

[mcruzdev]

@diegostalder I think we do not have this info documented.

cc: @EricWittmann

[EricWittmann]

Unfortunately the documentation is poor or missing. This project started out its life as mostly an Apicurio internal thing. If someone wanted to open a new GH issue about missing docs, that would be great. I can work on that in the future and use the issue for tracking.

[mcruzdev]

Hi @EricWittmann, Is there any place where I can add it? I got this documentation https://www.apicur.io, but I do not know what is the best place.

[EricWittmann]

I would suggest we start with markdown formatted documentation in a new ./docs folder in this repository. I suggest we use mkdocs to then convert the markdown into HTML for publishing on the apicur.io web site.

I will create a simple initial layout (hello world) set of docs for this, so we can start iterating.

[EricWittmann]

OK I've added a basic mkdocs style "./docs" directory with mostly generated content to get us started. Let me know what you think.

[mcruzdev]

Great @EricWittmann, it is a good start!

[EricWittmann]

I will say that the documentation site created by mkdocs is really nice. Once we have some additional content I can work on a theme for mkdocs that will match the apicur.io web site.