instructions for how to install the java jar version of codegen.

[Tomcli]

@ckadner we probably need a set of instructions for how to install the java jar version of codegen. Homebrew and maven plugin might be too complicated and it may change based on the user's java/brew config.

Originally posted by @Tomcli in #71 (comment)

[Tomcli]

I think this wget command can do the trick, but mac users need to install wget first

brew install wget

wget https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.8/swagger-codegen-cli-2.4.8.jar -O swagger-codegen-cli.jar

[ckadner]

@Tomcli -- The choice is either Homebrew or downloading the jar file. Maven should not be needed unless building the swagger-codegen jar from source is desired.

Our instructions currently also link to the swagger-api/swagger-codegen on GitHub, which should provide the details on other install or build option.

Did you want to copy this excerpt from there?

# Download current stable 2.x.x branch (Swagger and OpenAPI version 2)
wget https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.10/swagger-codegen-cli-2.4.10.jar -O swagger-codegen-cli.jar

java -jar swagger-codegen-cli.jar help

...and maybe add a command alias to make it compatible with the existing shell scripts we have:

# add this alias to your `~/.profile` or create it for any new Terminal shell session where you run api/codegen.sh
alias swagger-codegen="java -jar swagger-codegen-cli.jar"

# or create and export a `swagger-codegen` function before running the script `api/generate_code.sh`
function swagger-codegen() { java -jar swagger-codegen-cli.jar "$@"; }
export -f swagger-codegen

[Tomcli]

yes, I think the swagger-codegen repo can be too confusing especially for junior developers. Also I remember 2.4.10 might change some schema on the MLX? I remember back then I have to downgrade the codegen-cli to 2.4.8 in order to not change some of the schema.

[Tomcli]

also the homebrew command is always installing the latest codegen 2.4.x (right now is 2.4.20). If we can't support that version then maybe we need to note it down.

[ckadner]

The latest swagger-codegen@2 formula 2.4.20 from Homebrew works fine as well. Just tested it.

Not sure what you may have experienced with respect to

"... swagger-codegen 2.4.12+ ... not matching with the MLX schema ..."

[Tomcli]

When you run ./generate_code.sh, it was generated some code differences. Is there any extra step we need to do?

[ckadner]

When you run ./generate_code.sh, it was generated some code differences. Is there any extra step we need to do?

Oh, yes, that's true. I added some fixes for that in previous commits and corrected the Git master branch reference to main in PR #59

[ckadner]

When you run ./generate_code.sh, it was generated some code differences. ... any extra step we need to do?

Yes. I had codified the required post-processing in the script api/generate_code.sh to undo the undesired codegen results, by doing a codegen before and after making changes to api/swagger/swagger.yaml. I generate a reverse patch from the changes resulting by running codegen.sh before having done any changes to the Swagger API spec.

I will do an evaluation of the various swagger-codegen-cli.jar version to see which version is best suited for regenerating the API server stubs without causing too many undesired code changes that need to be undone by post-processing the generated code.