OpenAPITools / OpenAPITools/openapi-generator

[REQ] Add documentation for each server stub generator about how to use it

Open
#1,857 7 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Enhancement: Feature
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.