OpenAPI Ggenerator and Swagger Codegen look very similar on the surface. A little digging reveals that OpenAPI Generator was forked from Swagger Codegen in 2018 by a group of the Swagger Codegen community and contributors who wanted to proceed in a slightly different direction. Their stated goals were to speed up development and acceptance of new features, improve the quality and maintainability of the code base, and make it easier for new contributors to get involved.

Swagger Codegen is sponsored by SmartBear Software, while OpenAPI Generator is community-driven. Both are actively maintained and distributed under the Apache-2.0 license. OpenAPI Generator has more stars/forks even though it's a newer project. OpenAPI Generator has (in my opinion) much better docs.

@dcaro What is our plan for creating the Toolforge CLI from the autogenerated SDK? Manually? Automatically with a post-generation script?

In T356261#9620170, @Slst2020 wrote:

@dcaro What is our plan for creating the Toolforge CLI from the autogenerated SDK? Manually? Automatically with a post-generation script?

Will depend on the quality of the code generated, though I expect that there will always be some manual things we want to check, we could easily just create a new MR with the changes when any of the APIs is changed, for someone to review and merge right away if possible, or manually adapt if not.

So I guess eventually we might want something like:

Any api change -> generate toolforge python libs -> create MR on the toolforge cli to upgrade

Though we might start with something like:

Any api change -> create MR on the toolforge cli with the generated libs embedded

We can decide once we have the common API exposed though, no need to solve the problem yet.

In T356261#9620196, @dcaro wrote:

In T356261#9620170, @Slst2020 wrote:

@dcaro What is our plan for creating the Toolforge CLI from the autogenerated SDK? Manually? Automatically with a post-generation script?

Will depend on the quality of the code generated, though I expect that there will always be some manual things we want to check, we could easily just create a new MR with the changes when any of the APIs is changed, for someone to review and merge right away if possible, or manually adapt if not.

Even assuming that the generated SDK does not need any manual changes, we would still have to create/modify the CLI for each change to the API. So if there is a change in the API that introduces a new endpoint, the autogenerated client will have a new method dealing with that, but implementing the CLI wrapper is still up to us. I'm not sure my original question was clear.

Even assuming that the generated SDK does not need any manual changes, we would still have to create/modify the CLI for each change to the API. So if there is a change in the API that introduces a new endpoint, the autogenerated client will have a new method dealing with that, but implementing the CLI wrapper is still up to us. I'm not sure my original question was clear.

Can you elaborate on your question? (in case I did not answer the question you were asking xd)

Returning to the original intent of this task, there seem to only be two good alternatives, OpenAPI Generator and Swagger Codegen (links in task description). Of these, my recommendation would be OpenAPI Generator based on discussion in earlier comments.

@dcaro, do you think it would be okay to just pick one, or do we need a decision request? And/or further exploration, e.g. comparing generated SDKs?

In T356261#9799284, @Slst2020 wrote:

Returning to the original intent of this task, there seem to only be two good alternatives, OpenAPI Generator and Swagger Codegen (links in task description). Of these, my recommendation would be OpenAPI Generator based on discussion in earlier comments.

@dcaro, do you think it would be okay to just pick one, or do we need a decision request? And/or further exploration, e.g. comparing generated SDKs?

Might be nice to try both see what they offer though I'm ok with not needing a decision request for it.u
I'd wait until we have authentication sorted out, otherwise you'll have to manually add the authentication bits (might not be too hard though).

Note also that without auth the code generated would be only for usage from within toolforge.

Trying with just the builds-api openapi.yaml and openapi-generator, it doesn't like the .common section

(openapi-experiments) [~/repos/work/openapi-experiments (main)] %    openapi-generator generate -i builds-api.yaml -g python -o python-client-sdk
Exception in thread "main" org.openapitools.codegen.SpecValidationException: There were issues with the specification. The option can be disabled via validateSpec (Maven/Gradle) or --skip-validate-spec (CLI).
 | Error count: 1, Warning count: 1
Errors:
	-attribute .common is unexpected
Warnings:
	-attribute .common is unexpected

	at org.openapitools.codegen.config.CodegenConfigurator.toContext(CodegenConfigurator.java:717)
	at org.openapitools.codegen.config.CodegenConfigurator.toClientOptInput(CodegenConfigurator.java:744)
	at org.openapitools.codegen.cmd.Generate.execute(Generate.java:527)
	at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
	at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)

Running with the --skip-validate-spec works, but produces different results than generating with the old yaml, before the refactor to use .common

I think those changes are mostly because the api changed? We wrap now all the responses with a messages response ({"messages": {"info":[], "warning":[], "error":[]}, ...}).

Have you tried with the joint openapi.json? (https://api-docs.toolforge.org/openapi.json)

sstefanova opened https://gitlab.wikimedia.org/repos/cloud/toolforge/components-api/-/merge_requests/27

openapi: generate operationIds from route names

sstefanova merged https://gitlab.wikimedia.org/repos/cloud/toolforge/components-api/-/merge_requests/27

openapi: generate operationIds from route names

dcaro merged https://gitlab.wikimedia.org/repos/cloud/toolforge/toolforge-deploy/-/merge_requests/544

components-api: bump to 0.0.21-20241107105745-795f4143

project_1317_bot_df3177307bed93c3f34e421e26c86e38 opened https://gitlab.wikimedia.org/repos/cloud/toolforge/toolforge-deploy/-/merge_requests/584

components-api: bump to 0.0.48-20241010123512-f12ab9d2