k8s-openapi VS spectrum

It's called sans-io in Python land, which is where I heard it first.

https://sans-io.readthedocs.io/

I did it for one of my projects back in 2018 https://github.com/Arnavion/k8s-openapi/commit/9a4fbb718b119...

Another option is to implement your API in a sans-io form. Since k8s-openapi was mentioned (albeit for a different reason), I'll point out that its API gave you a request value that you could send using whatever sync or async HTTP client you want to use. It also gave you a corresponding function to parse the response, that you would call with the response bytes however you got them from your client.

https://github.com/Arnavion/k8s-openapi/blob/v0.19.0/README....

(Past tense because I removed all the API features from k8s-openapi after that release, for unrelated reasons.)

Macro expansion is slow, but only noticeably in the specific situation of a) third-party proc macros, b) a debug build, and c) a few thousand invocations of said proc macros. This is because debug builds compile proc macros in debug mode too, so while the macro itself compiles quickly (because it's a debug build), it ends up running slowly (because it's a debug build).

I know this from observing this on a mostly auto-generated crate that had a couple of thousand types with `#[derive(serde::)]` on each. [1]

This doesn't affect most users, because first-party macros like `#[derive(Debug)]` etc are not slow because they're part of rustc and are thus optimized regardless of the profile, and even with third-party macros it is unlikely that they have thousands of invocations. Even if it is* a problem, users can opt in to compiling just the proc macros in release mode. [2]

[1]: https://github.com/Arnavion/k8s-openapi/issues/4

[2]: https://github.com/rust-lang/cargo/issues/5622

>OpenAPI Generator allows generation of API client libraries from OpenAPI Specs

It does, but the generated code can be very shitty for some combinations of spec and output language. I maintain Rust bindings for the Kubernetes API server's API, and I chose to write my own code generator instead. The README at https://github.com/Arnavion/k8s-openapi has more details.

k8s_openapi - https://github.com/Arnavion/k8s-openapi

For example: I have a routine that checks the value of (from k8s-openapi): Ingress -> IngressStatus -> LoadBalancerStatus -> Vec[0] -> String

As the maintainer of the Rust bindings that the library used in the article (kube) is backed by, I can confirm that Kubernetes' openapi spec requires a lot of Kubernetes-specific handling to generate a good client than generic openapi generators do not provide.

See https://github.com/Arnavion/k8s-openapi/blob/master/README.m... for a full description.

I also confirm that I keep it up-to-date with Kubernetes releases and have been doing so for the ~3 years that it's been around. Not just the minor ones every few months, but even the point ones; these days the latter usually only involves updating the test cases instead of code changes and they're done within a few hours of the upstream release.

Disclosure: I'm a contributor to the project.

OpenAPI Spec and auto-generated API clients are very useful when multiple languages need to be supported, like when running a developer program. I've worked at companies that both use OpenAPI Generator for official clients and ones that wrote our own tools for API client SDK generation (with different design philosophy). I've used a number of generators myself to compare and submitted fixes / enhancements to OpenAPI Generator. I used the Go client generator a while back and compared it to others, and recently started using the Crystal one.

To get the most the project, the following is useful: (a) need to support multiple languages, (b) ability to update the generator's code, both in Java and templates (Mustache or Handlebars), and (c) ability to discuss design in GitHub issues and the Slack channel.

The nice thing about OpenAPI Spec is that there is an ecosystem of tooling to support it, including rendering API references (HTML and PDF), API explorers (HTML pages to execute API calls), API clients, etc. But there is a learning curve. For writing specs by hand, I use and favor the Stoplight Studio IDE ( https://stoplight.io/studio ). For programmatically analyzing and editing specs, which is especially useful for finalizing auto-generated specs, I've built an OpenAPI Spec SDK library to make this easier ( https://github.com/grokify/spectrum ).