search

OpenAPITools / openapi-generator

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)
https://openapi-generator.tech
Apache License 2.0
21.35k stars 6.46k forks source link

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

Open mohamnag opened 5 years ago

mohamnag commented 5 years ago

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

jimschubert commented 5 years ago

@mohamnag thanks for opening this issue. I agree the documentation for nearly all generators requires a quality and usability check. More clearly documenting how to use the project is on our short-term roadmap (and I have an open PR (#1770) to introduce a new guide-based project site.

Most of our server generators are meant to be stubs only, and so many of them generate controller classes (or whatever architectural design) which are meant to be directly modified.

Very few support regeneration of server stubs in a way similar to the Java Springboot template. The reason, I believe (but I'm no expert on the origins of the original project pre-fork), is that there's no way to do this cleanly in some languages. We generally tend toward a consistent workflow across generators but as you can see the community contributions from two authors for the same framework in two different languages can differ quite a bit.

I know your issue is request the general feature enhancement of improving the generated READMEs for all server stubs, but I was wondering if your preference as a user would be to have the kotlin-spring generator also generate interfaces which return NOT_IMPLEMENTED responses? I'm not a Spring user myself, but I could check with the author regarding an update or open a new issue to modify this generator specifically.

mohamnag commented 5 years ago

Thanks for the through response. Now that I have worked with the kotlin-spring generator, I found out that it actually supports the generation gap pattern but for that it should be configured properly.

I also agree with you that it is impossible for all languages to follow exactly same pattern. Lots of them have different solutions and the solution should match the mindset of developers in target language and not the one in which this tool is written. That's the reason I thought each generator needs its own documentation on how it's results shall be used and which pattern(s) it follow. It could be that some of the generators share patterns but still it is worth the effort to document it separately or maybe have a common page for shared part of the concept and then detail it in separate places.

jimschubert commented 5 years ago

For contributors, here's a checklist that any of us can toggle the checkbox after reviewing or modifying server stub generator documentation.

I think we should standardize on:

Are there any other considerations before reviewing all server generator readmes?

(also, if you tick one of the checkboxes please leave a comment that you've reviewed or tag this issue in a PR for release tracking)

ybelenko commented 5 years ago

Including links back to openapi-generator

@jimschubert, Does codegen have property with the link? It's better to store that link in DefaultCodegen properties, then use harcoded value in mustaches.

Are there any other considerations before reviewing all server generator readmes?

I would add How to run tests and Migration Guides, but I think Explanation of usage section is already includes this topics.

Maybe we can add template creator at the end of README, so user can know how's responsible for generator.

jimschubert commented 5 years ago

@ybelenko one concern I would have with adding the template authors is that we can't update the code once someone generates it, so embedded author information is immediately "stale". For instance, if you've authored MySQL and lose interest in this project after 6 months, a consumer might message you directly after a year and ask for support. I think it would be sufficient to link to the project directly since our current list of maintainers would always be accurate (at least on master).

I think most generators that support tests already describe how to run the test suite, but that's a good point to double check.

Could you elaborate on "Migration Guide"? To me this sounds like a guide to migrate from one generated version to another? For server/doc/config generators I don't think that's relevant. But for client generators, I could see us putting this info into a changelog so those generating the code can opt-out by adding that file to .openapi-generator-ignore.

ybelenko commented 5 years ago

Could you elaborate on "Migration Guide"? To me this sounds like a guide to migrate from one generated version to another? For server/doc/config generators I don't think that's relevant.

@jimschubert Really? Let's take PHP Slim server generator as example that I'm responsible for. To migrate from 3.x version to 4.x version user must:

How is that not important? Maybe some users will not upgrade when migration requires too much effort.

Including links back to openapi-generator

Where we should place these links(at the bottom, I guess)? And what links exactly?

jimschubert commented 5 years ago

@ybelenko Your PHP example assumes that a user will be regenerating a server over existing generated or hand-written code. I have a feeling that this is a very small set of our users. The migration steps you present are things that should already be included in the generator's requirements.

Consider a first-time user of the generator for 4.x. They'll be starting fresh, and having a "migration guide" in a newly generated README would probably be confusing.

I'm not saying this information isn't useful, I just think a README would be the wrong place for it... especially because people usually expect to read steps in upgrading before actually upgrading.

Maybe we could open another issue to discuss the topic of how to effectively communicate upgrade steps before generation?