OpenAPITools / OpenAPITools/openapi-generator
[REQ] Add documentation for each server stub generator about how to use it
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
Is your feature request related to a problem? Please describe.
I just found this project and as a new user it took me a lot of time to find out how the generated code (for server stubs) is supposed to be used.
For example I was interested in two generators spring and kotlin-spring. One is generating controller classes that have additional methods which can easily be overwritten in a subclass and implemented. It is not even necessary to include the generated sources in the project and they can be included as a dependency.
The kotlin-spring one, on the other hand, generates controllers that should be included as source and updated directly.
Even for two generators which are pretty much similar, it was hard to find out a best solution and even those may not be the way developers of the generators meant to be used. This can cause other problems when future changes breaks the way generator is used and at some point might defy the reason this generator is used (which is saving time).
Describe the solution you'd like
It would be nice if each generator described in its documentation not only the options it is providing but also how the generated code is supposed to be used.
Describe alternatives you've considered
none?!
Additional context
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the documentation for the spring and kotlin-spring server stub generators and compare how each generated output is intended to be integrated. Done means each generator's documentation explains how its generated code should be used and maintained; the issue does not name specific documentation files or tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, kotlin, spring
- Domain
- backend, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100