controller-tools swagger command

[Tom Eyckmans]

Hi,

I am working on adding a new command to controller-tools to generate a not-flattened swagger specification. It re-uses the markers of the crd command.

The main goal is to have a swagger specification that exposes the internal model, this is important for code generation tools (like kuberig that generates kotlin code) for various reasons but the main reasons:

- preserve names of the object types

- reuse of object types is clear

Is there interest in adding this?

I got a first version working for tektoncd/pipeline. It is particularly interesting because it doesn't share anything at all of the model in the CRD definitions.

Working on it here: https://github.com/teyckmans/controller-tools/tree/swagger

Example of the swagger that is generated can be found here: https://github.com/teyckmans/pipeline/blob/crd-swagger/config/crd/swagger/swagger.json

ps: This is the first time I am doing anything with GO, so if it is not done in a GO-way you know why.

Thanks,

Tom

[Solly Ross]

A couple of comments/suggestions:

1. I'd be surprised if you had to fork the whole `/crd` package -- you should just be able to use /crd.Parser as an import, but call NeedSchema instead of NeedFlattenedSchema.
2. Be aware that the k8s API server can and does expand/modify the generated openapi, so whatever you get from generating locally isn't the whole picture.

Best Regards,

Solly (@directxman12)

--
You received this message because you are subscribed to the Google Groups "kubebuilder" group.
To unsubscribe from this group and stop receiving emails from it, send an email to kubebuilder...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/kubebuilder/0674534c-ebdd-4796-b097-ef40e790c195n%40googlegroups.com.

[Tom Eyckmans]

Hi Solly,

Thank you for having a look!

1. Sure thing, I had first tried to build the swagger model in the parser. But that did not work out.

While generating the definitions part I encountered some Schemata that was not available, tried to solve that by calling NeedFlattenedSchema but it did not make all the Schemata available or it looked like it anyway. Should work with NeedSchema indeed I am now loading schemas when following references.

2. Interesting, do you mean this: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/ ? If I understand it correctly it is about adding new URLs/paths. I am generting the kuberig dsl for the vanilla k8s here https://github.com/teyckmans/kuberig-dsl-kubernetes when there are api-extensions it would really need to be generated from the api-spec of the k8s instance. I have to think about how else this can be supported.

Kr,

Tom (@teyckmans)

Op woensdag 23 september 2020 om 21:34:35 UTC+2 schreef soll...@google.com:

[Tom Eyckmans]

Hi Solly,

Made the swagger command reuse the crd/parser. This did require some minor changes, the main thing was that the swagger command needs all the json references to be absolute.

Also processed all errors the test.sh script threw at me.

Kind regards,

Tom

Op donderdag 24 september 2020 om 06:48:04 UTC+2 schreef Tom Eyckmans:

[Tom Eyckmans]

Added some improvements to the swagger command and brought it up-to-date with upstream master.

Also tested it for cert-manager.io and cloudstate in addition to tektoncd/pipeline.

Also had to add DNSPolicy to the known types.

One thing is bothering me, I've had to add a separate parameter to be able to filter what directory is scanned for CRD types.

I was thinking that I would be able to use the `paths` parameter but that does not work. if I use that the absolute reference resolution fails. Which is a pitty. Not sure if there is an easy fix for this.

Kind regards,

Tom

Op vrijdag 25 september 2020 om 08:12:17 UTC+2 schreef Tom Eyckmans: