question: I've left "language" as a required option for the CLI and maven plugin, but I'm wondering if we should go ahead and make both language and generatorName optional from the start? My reasoning for leaving it as required is that existing users will have this option anyway, so required/optional won't matter. However, now that I think about it, the warning message says to "use generatorName instead" and if a user does this and removes "language", they'll be told that language is required.

Thoughts on going ahead and making both optional for now, and exposing an error manually if neither is set? I think this would ease both migration for existing users and onboarding for new users.

This is nice, looks good to me!

I think in the CLI there is also the option to output all available langs:

openapi-generator-cli langs

Or something like that, this should be changed to generators (with backward compatibility => we keep langs in parallel during one release)

There are also error message, when an invalid lang is selected, that says "available languages" => should be changed to "available generators"

We also need to update our migration guide:
https://github.com/OpenAPITools/openapi-generator/blob/master/docs/migration-from-swagger-codegen.md

I thought you wanted also to fail (have an error) if both "language" and "generator name" are set. Maybe I missed it from your code.

If I remember well you also mention something about supporting old generator names during one release to ease the mig.

Maybe we can add this map somewhere:

Map<String,String> nameMigrationMap = new HashMap<>();
nameMigrationMap.put("akka-scala","scala-akka");
nameMigrationMap.put("scala", "scala-httpclient");
nameMigrationMap.put("jaxrs", "jaxrs-jersey");
nameMigrationMap.put("qt5cpp", "cpp-qt5");
nameMigrationMap.put("cpprest","cpp-restsdk");
nameMigrationMap.put("tizen", "cpp-tizen");
nameMigrationMap.put("sinatra","ruby-sinatra");
nameMigrationMap.put("swift", "swift2-deprecated");
nameMigrationMap.put("lumen", "php-lumen");
nameMigrationMap.put("slim","php-slim");
nameMigrationMap.put("ze-ph", "php-ze-ph");
nameMigrationMap.put("nancyfx","csharp-nancyfx");

And do a if map.containsKey() then output a warning and use the new new instead of the old. We can support this for both "language" and "generator-name" options.

question: I've left "language" as a required option for the CLI and maven plugin, but I'm wondering if we should go ahead and make both language and generatorName optional from the start?

I think both optional is good and error if both are set or if both are missing.

@jmini thanks for doing such a thorough evaluation. I hadn't even considered the langs command!

I'll make the improvements you've listed above. I think the nameMigrationMap check makes the most sense in the new setGeneratorName setter. Since I pass setLang to this method, it would be a single point in code to manage the migration mapping.

I'll change the title of the PR to indicate it's a work in progress. Should we add a WIP label as well?

I've pushed some changes. I've deprecated the lang CLI option, as this may likely list languages only (rather than generator) in the future.

To list generators, I've created list which outputs to a long-format, separated by headers of generator type. I've provided a --short switch to output a parseable/scriptable CSV option.

Last push also includes the mapping for the lang->generator-name renames as defined in the wiki. Once this is merged, we can update the wiki's mention of the -l switch.

I have spotted 2 small changes in the MoJo.

As indicated by @kenisteward on Gitter, I think it is I good idea to update the docs in this PR:

• docs/integration.md => replace with new values
• modules/openapi-generator-maven-plugin/README.md => new values
• README.md => -l switch mentioned in Docker section and other like the help message that is now "generators" instead of "langs"
• ...

And in the docs/migration-from-swagger-codegen.md we need a new section to say that there is a change.

@jmini all great feedback. Thanks!

Do you think it's necessary to update the migration doc? It's not required to make the changes to the language switch in order to migrate, and it will want the user. I guess now that it's not required to change the language values, either, that it makes sense to list for consistency.

@jimschubert: I have named it "migration guide" but this is also a "what are the main differences between Swagger-Codegen and OpenAPI Generator".

After New maven coordinates section I would create 2 new sections:

• Changes in the CLI
• Changes in Maven Plugin

In each new section I would summarize what have changed with one or two sentences.

In New generators names section, I would add one sentence to say that OpenAPI Generator is tolerant with old names during one release.

@jmini Thanks again for the second pair of eyes.

I had originally left all -l instances in scripts because the option is still valid, but on second thought I wanted these to be "current" and not produce a warning by default on initial release. Because there were about 500 locations that all had to be verified individually and changed manually, I've broken changes down into many separate commits to make them easier to scan.

I was wondering, what determines that docs should exist under /docs rather than in the wiki? It looked like you created or edited most of those files, and some of the information seems duplicated or like there are empty placeholders on the wiki:

• https://github.com/OpenAPITools/openapi-generator/blob/master/docs/integration.md vs https://github.com/OpenAPITools/openapi-generator/wiki/Workflow-integration
• https://github.com/OpenAPITools/openapi-generator/blob/master/docs/customization.md vs https://github.com/OpenAPITools/openapi-generator/wiki/Customizing-client-code-generation ) and others)

Are we intending to move those under the folder to the wiki, or are we planning to deprecate the wiki in favor of source control docs?

It looked like you created or edited most of those files

@wing328 extracted those files from the README with c32ef12

I just moved them into a docs/ folder with 3d7eaf9

Yes we we have planned to move more content into the repository (and remove them from the wiki).

Multiple reasons for that:

• Documentation belongs to software change, have a look at this PR, it is great to be able to discuss what needs to be documented.
• GitHub Wiki does not support PR workflow, which is a great way to do suggestions, reviews and improvements
• Wiki are not forked in GitHub forks, you need to migrate them separately (they are git repositories, but not well integrated in GitHub UI).
• Software documentation follows the software branches. Imagine we works on 4.0 and do some bugfix release for 3.0 on a separated 3.x-maintenance branch. With a GitHub wiki you just have a master branch, you can not support both versions in parallel.
• On the long term the plan is to generate the documentation inside a static website. For that we might need some artefacts that comes from the code itself (like for example the help in the command line that you have updated by hand). In the docs page there should be a placeholder that some content will be injected, and the static-website build tool should put the correct values in the built html manual. When we have this it make even more sense to single source everything in one repo and not in two.

I would say that we should migrate the content of the wiki into some files in the docs/ folder. This can be a step-by-step process. I you spot something outdated in the wiki that have already its counterpart in the docs just delete it and replace it with a link to the new page.

@jmini I fully agree with moving things to /docs for the reasons you posted above. Also, docs in the repository support all of github's templating (asciidoc, csv rendering, etc).

I think we should migrate everything from the wiki, as I find it confusing that there are multiple places for all of these details and I'm not easily able to do a search across the project from the wiki. I could fork the wiki into a subdirectory, but that wouldn't share a commit with this PR.

The FAQ (wiki) that I originally created intends to be community driven FAQ as anyone can update it easily without a PR. (we did see contributions from the community to add more FAQs over time)

The Q&A (mainly for the launch of openapi-generator) is not something I want people to update without approval/review as it represents our viewpoints.

I agree it may confuse users and happy to see consolidations or other approaches to make our doc more useful and easily discoverable by our users.

This discussion about "docs/ vs wiki" has nothing to do with this PR, I have opened #103 (it will be easier to find it later).

@jmini I think the /docs discussion is relevant here, as it has lots of -l occurrences that would need to be changed once this is merged. I don't think the /docs vs wiki discussion has to be solved here, just whether those pages are intended to be kept up-to-date or if the /docs were only a placeholder as we migrated the wiki. What I didn't want to happen is for me to move content from /docs to the wiki or vice versa as a follow up.

Sorry if I didn't clarify the reasoning for my question previously.

It is OK. Better more text to clarify than misunderstanding. I have updated my comment to say that the "docs vs wiki discussion" was moved to an other issue.

It is great that you have updated the docs, and the bin/ scripts.

Tell us when you consider this ready for test.

@jmini this is ready to test. Sorry, I thought I had included that in my comment after the last push.

@jimschubert can you solve the conflicts created by #124 so that we can merge this?

During the merge, for each conflict inside the bin/ folder you can take the master version and then redo a search and replace -l => -g.

@jmini @wing328 I've fixed these merge conflicts. I've also added an exit code of 1 if the CLI is called without args, to indicate failure. I didn't test whether the airlift framework also does this on help, which is common behavior… but I think that's not important unless we change the default command to help.