We need to explain in documentation the recommended way for types generation

asyncapi / generator

Use your AsyncAPI definition to generate literally anything. Markdown documentation, Node.js code, HTML documentation, anything!

https://asyncapi.com/docs/tools/generator

Apache License 2.0

772 stars 235 forks source link

We need to explain in documentation the recommended way for types generation #1042

Closed derberg closed 10 months ago

derberg commented 1 year ago

in main overview we need clear info that if people are interested only in types/model generation, they should use modelina directly
we also need a separate document with some example that explains that better to use modelina for models generation, if template requires it. We have examples like https://github.com/asyncapi/ts-nats-template/blob/master/template/src/models/models.js for example

@jonaslagoni wdyt?

black-snow commented 1 year ago

Yes please. I just opened an issue for I want models only and I only got here by accident.

jonaslagoni commented 1 year ago

Makes sense to me yea 👍

For the template integration, I am not really the biggest fan of the current way to do it as it's "good enough" 😅 But yea, definitely need some documentation to show this. Also has an outstanding issue in Modelina to document this: https://github.com/asyncapi/modelina/issues/641

derberg commented 1 year ago

you mean it could be done better?

jonaslagoni commented 1 year ago

Always 😄 But yea, the integration feels a bit rough right now. Never the less we can of course document it as is and it can always be improved later.

derberg commented 1 year ago

ok so the scope (writing it as I put it up for bounty) is to:

clarify in main doc, probably intro that for only-model generation better people look int modelina and use cli to generate models
have a dedicated doc that explains that when developing template, client or server code, where models generation is also important, the modelina library should be used - and how (some code snippets)

@jonaslagoni anything specific from your side? I think https://github.com/asyncapi/ts-nats-template/blob/master/template/src/models/models.js is the best example (with additional code comments), unless you think it makes sense to have another one with custom preset? I don't think so, better link directory to modelina examples right? as it is not much about generator-functionality. Also, you would probably like to provide 2.0 version of above mentioned example?

aeworxet commented 1 year ago

Bounty Issue's End Of Life (EOL): 2024-02-29 23:59:59 UTC-12:00

mhmohona commented 1 year ago

Would like to work on this.

Florence-Njeri commented 1 year ago

Hey @derberg I'd love to work on this issue

derberg commented 1 year ago

Since @Florence-Njeri is a maintainer in this repo, she has priority. For transparency: I also contacted Florence before putting this issue under bounty to make sure she has time to work on the issue as she knows the generator docs the most

aeworxet commented 1 year ago

Bounty Issue's Timeline

Complexity Level	Assignment date (by GitHub)	Start date (by BP rules)	End date (by BP rules)	Draft PR submission	Final PR submission	Final PR merge
Medium	2023-11-07	2023-11-13	2023-12-22	2023-11-24	2023-12-08	2023-12-22

Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.

aeworxet commented 1 year ago

Due to unpredicted circumstances that could not be foreseen and are beyond the control of the AsyncAPI Maintainer (@derberg), the Bounty Issue's Timeline is frozen for an indefinite amount of time.

aeworxet commented 12 months ago

AsyncAPI Maintainer (@derberg) had regained a confident online presence in Slack, so the Bounty Issue's Timeline is extended by four weeks.

Bounty Issue's Timeline Extended

Complexity Level	Assignment date (by GitHub)	Start date (by BP rules)	End date (by BP rules)	Draft PR submission	Final PR submission	Final PR merge
Medium	2023-11-07	2023-11-13	2024-01-19	2023-12-22	2024-01-05	2024-01-19

Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.

derberg commented 11 months ago

@Florence-Njeri hey, do you need some help?

Florence-Njeri commented 11 months ago

@aeworxet @derberg Sorry for the delay. I'm hoping to open up my draft PR by end of week. @derberg Incase of blockers I'll let you know on Slack

derberg commented 11 months ago

thanks @Florence-Njeri fyi I'm out next week cause of christmas and new years eve travel

aeworxet commented 11 months ago

@asyncapi/bounty_team

Florence-Njeri commented 11 months ago

@derberg @asyncapi/bounty_team @aeworxet here is the PR: https://github.com/asyncapi/generator/pull/1096

aeworxet commented 11 months ago

AsyncAPI Maintainer (@derberg) was absent online in Slack for one period of three working days in a row, so all remaining target dates of the Bounty Issue's Timeline are extended by two calendar weeks.

Bounty Issue's Timeline Extended

Complexity Level	Assignment date (by GitHub)	Start date (by BP rules)	End date (by BP rules)	Draft PR submission	Final PR submission	Final PR merge
Medium	2023-11-07	2023-11-13	2024-02-02	2023-12-22	2024-01-19	2024-02-02

Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.

aeworxet commented 10 months ago

@Florence-Njeri, please provide an update to the PR.

Florence-Njeri commented 10 months ago

Hi guys, @aeworxet @asyncapi/bounty_team I am currently addressing PR feedback from @derberg. The PR should be merged by end of week

quetzalliwrites commented 10 months ago

thank you so much @Florence-Njeri 💗

derberg commented 10 months ago

well done @Florence-Njeri 👏🏼

@aeworxet I confirm bounty issue is completed

aeworxet commented 10 months ago

Bounty Issue Completed 🎉

@Florence-Njeri, please go to the AsyncAPI page on Open Collective and submit an invoice for USD 200.00 with the expense title Bounty generator#1042, tag bounty, and full URL of this Bounty Issue in the description.