Notes on the generator

[jonschoning]

Several months ago, the folks at SmartBear (who own the repo for swagger-codegen [1] ) decided to do a re-write while moving from supporting the 2.0 openapi spec to 3.0.

However, in this process, they also changed the templating language from mustache to handlebars - invalidating existing languages - essentially existing work for each language would have to be re-built from scratch.

This caused a split in which the primary open-source contributors left, and forked swagger-codegen into a new repo "openapi-generator" [1] - which focuses on an incremental path to support of the openapi 3.0 spec, and not moving to handlebars templates or throwing out existing work on generators, and focusing more on backwards-compatibility.

I've included the haskell-http-client generator in the new openapi-generator, which has been merging my pull requests promptly, and in which i also have commit rights.

I've tried submitting PR's to swagger-codegen, but they have not been merging any PR's lately.

the upshot:

1. Continue to use swagger-codegen. For now, the breaking changes are only on the 3.0.0 branch and master still includes the old haskell-http-client. If they switch master to 3.0.0 at some point haskell-http-client probably won't be available there anymore. You could continue to target an existing commit for the generator, but probably not be able to get any changes made to the haskell-http-client generator very easily. So, If the current version of the generator is serving your needs adequately, then all is good.

2. Switch to openapi-generator. It's pretty much backwards compatible, but some cli arguments may be depricated. Also i'm not sure if the build process here supports targeting a different repo than swagger-codegen. If more features/changes in the generator are desired though, it would be much easier to make them in openapi-generator.

As of today, I haven't made extensive changes to the haskell-http-client generator, so there is not much difference in features from swagger-codegen vs. openapi-generator.

Question: Are there any ongoing/steady users of kubernetes-client/haskell ?

[1] https://github.com/swagger-api/swagger-codegen
[2] https://github.com/OpenAPITools/openapi-generator

[alexjg]

I'm not an ongoing user yet but I would like to be. My main impediment at the moment being getting this onto hackage. On that basis and given the discussion in #27 I would be in favour of option two. My main reason being that I think we'll probably need to massage the output of the generator a bit to achieve the package organisation discussed in that PR.

[jkachmar]

I'm a potentially interested user as well, but I'm hesitant to pick up the library until some of this stuff has stabilized.

Is there anything I could do to help either this process or the one outlined in #27 to get it on Hackage?

[jkachmar]

I've tried generating the client code with the OpenAPI generators and have run into the errors below.

No idea what the root cause might be, unfortunately, although I've seen some issues with similar errors (e.g. OpenAPITools/openapi-generator#2236).

Log Snippet

[WARNING] codegenModel is null. Default to UNKNOWN_BASE_TYPE
[WARNING] Multiple MediaTypes found, using only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] Multiple schemas found in content, returning only the first one
[WARNING] The following schema has undefined (null) baseType. It could be due to form parameter defined in OpenAPI v2 spec with incorrect consumes. A correct 'consumes' for form parameters should be 'application/x-www-form-urlencoded' or 'multipart/form-data'
[WARNING] schema: class ObjectSchema {
    class Schema {
        title: null
        multipleOf: null
        maximum: null
        exclusiveMaximum: null
        minimum: null
        exclusiveMinimum: null
        maxLength: null
        minLength: null
        pattern: null
        maxItems: null
        minItems: null
        uniqueItems: null
        maxProperties: null
        minProperties: null
        required: null
        type: null
        not: null
        properties: null
        additionalProperties: null
        description: Patch is provided to give a concrete name and type to the Kubernetes PATCH request body.
        format: null
        $ref: null
        nullable: null
        readOnly: null
        writeOnly: null
        example: null
        externalDocs: null
        deprecated: null
        discriminator: null
        xml: null
    }
    type: object
    defaultObject: null
}

[jonschoning]

@jkachmar Do you have a link to the spec file used that this failed on & have a link to it?
I had tested it with version": "v1.9.0, which is OAS 2.0.

I noticed the linked issue above was using oneOf, which is an OAS 3.0 features that is not well supported yet; if newer versions of the kubernetes are using OAS 3.0 features like oneOf, then there may be differences how openapi-generator and swagger-codegen parse it; in either case the haskell-http-client generator hasn't been updated yet for OAS 3.0 features.

[jkachmar]

I tested it with v1.11.8, which I think should still be OAS 2.0. I'm not at the computer I ran all this on, so I'll fork this and the gen repo to try and reproduce what I saw earlier when I get back to it.

[jonschoning]

I was able to compile the "processed" v1.11.8 spec manually with openapi-generator, although the cli option --skip-validate-spec was necessary.

It did output a fair amount of warnings, but they did not seem to impact the generated code & the stack build cmd completed fine:
https://gist.github.com/jonschoning/1bfc9385681d52d2361f8253b96ac05b.

I did not seem to encounter the same error in your log?

[jonschoning]

I tested out making the changes to /gen to use openapitools to regenerate the client.
the changes to /gen were pretty simple: jonschoning/kubernetes-client-gen@c1cb27a

after running ../kubernetes-client-gen/openapi/haskell.sh kubernetes settings, the results are here: jonschoning@6433ac6

The codegen is pretty much the same, save for the ordering of the "body" parameters.

On the other hand, it looks like they are now finally accepting some commits in 1) swagger-codegen swagger-api/swagger-codegen@ab14608 to udpate to stack lts-13.8. So it looks like some ability to update code there is possible, but I'm also not sure when they will be switching over to the 3.0.0 branch (master is on 2.4.1), and if/when they do switch over the haskell-http-client generator won't be available any longer, unless it is completely re-written as they have done with the other generators on the 3.0.0 branch.

[jkachmar]

Personally, I feel that since the Kubernetes clients for Ruby and Python clients here are switching over to the openapitools generators I feel like it makes sense to want to switch this one as well.

It also means that when/if the Kubernetes OpenAPI spec starts to use some features from OpenAPI v3 it would be easier to send a PR up to you that incorporates that functionality into the http-clientgenerator.

[guoshimin]

@jonschoning Awesome! Can you open a PR against the gen repo?

[jonschoning]

sure, will do
kubernetes-client/gen#108

[denibertovic]

This can probably be closed since the above PR has been merged.