From 719e5c6db13a25685c59d15d021f44f3c4898cf2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcel=20Wien=C3=B6bst?= Date: Wed, 23 Sep 2026 14:38:17 +0200 Subject: [PATCH 1/3] docs(adr): Add draft of OpenAPI generator ADR --- adr/0003-openapi-generators.md | 62 ++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 adr/0003-openapi-generators.md diff --git a/adr/0003-openapi-generators.md b/adr/0003-openapi-generators.md new file mode 100644 index 00000000..9f9a0006 --- /dev/null +++ b/adr/0003-openapi-generators.md @@ -0,0 +1,62 @@ +# OpenAPI Generators + +## Status + +proposed + +## Context + +The Python SDK code is currently fully manually written and maintained. The Java and JS SDKs use a code generator to generate low-level clients. It is planned to introduce code generation to the Python SDK as well. + +## Decision + +Use the [OpenAPI generator](https://openapi-generator.tech/) for code generation in the Python SDK in favor of other code generators. The extent to which the generator will be used will to be decided in future ADRs. + +## Consequences + +- For integrating the OpenAPI generator it is necessary to write and maintain preprocessing and postprocessing scripts as well as template files. +- For running the generator a Java runtime needs to be installed during development and in related workflows. +- The generator can be used to automatically monitor spec changes. +- Reduces maintenance efforts for the generated portions of the SDK. +- Aligns the Python SDK with the other SDKs, in particular Java, which uses the OpenAPI generator, too. + +## Appendix + +The following generators were considered (all except two were immediately ruled out): + +- [OpenAPI Generator](https://openapi-generator.tech/) +- [Kiota](https://github.com/microsoft/kiota) +- [OpenAPI Python Client](https://github.com/openapi-generators/openapi-python-client): ruled out because it is only sporadically maintained and has no Pydantic support +- [Datamodel Code Generator](https://github.com/koxudaxi/datamodel-code-generator): ruled out because it only generates models and not the full client +- [Hey API](https://github.com/hey-api/hey-api): ruled out because the Python generator is in alpha (as of September 2026) and not stable yet +- [Fern](https://github.com/fern-api/fern): ruled out because (despite being Open-source) it is a commercial product and has been acquired by Postman +- [Speakeasy](https://www.speakeasy.com): ruled out because it is a commercial product +- [Stainless](https://www.stainless.com/): not available anymore (as of September 2026) + +Commercial generators are not considered for multiple reasons, one of them being that this would make external contributions to the SDK more difficult. + +### Option A: OpenAPI Generator + +Pros: + +- well-established codebase/project +- Open-Source (Apache 2.0 license) +- has support for Pydantic, httpx and async + +Cons: + +- written in Java (however, templates can be used to control output) +- generated code is not Pythonic nor up-to-date to current typing conventions + +### Option B: Kiota + +Pros: + +- modern, actively maintained/developed generator +- Open-Source (MIT license) + +Cons: + +- written in C# with no templating support (limited customization options) +- no Pydantic support +- generated code is not Pythonic From 821a0f05ab900690d78917e07db12b20feced8c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcel=20Wien=C3=B6bst?= Date: Wed, 23 Sep 2026 14:46:54 +0200 Subject: [PATCH 2/3] small fixes --- ...{0003-openapi-generators.md => 0004-openapi-generators.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename adr/{0003-openapi-generators.md => 0004-openapi-generators.md} (95%) diff --git a/adr/0003-openapi-generators.md b/adr/0004-openapi-generators.md similarity index 95% rename from adr/0003-openapi-generators.md rename to adr/0004-openapi-generators.md index 9f9a0006..1efd0233 100644 --- a/adr/0003-openapi-generators.md +++ b/adr/0004-openapi-generators.md @@ -10,7 +10,7 @@ The Python SDK code is currently fully manually written and maintained. The Java ## Decision -Use the [OpenAPI generator](https://openapi-generator.tech/) for code generation in the Python SDK in favor of other code generators. The extent to which the generator will be used will to be decided in future ADRs. +Use the [OpenAPI generator](https://openapi-generator.tech/) for code generation in the Python SDK in favor of other code generators. The extent to which the generator will be used will be decided in future ADRs. ## Consequences @@ -31,7 +31,7 @@ The following generators were considered (all except two were immediately ruled - [Hey API](https://github.com/hey-api/hey-api): ruled out because the Python generator is in alpha (as of September 2026) and not stable yet - [Fern](https://github.com/fern-api/fern): ruled out because (despite being Open-source) it is a commercial product and has been acquired by Postman - [Speakeasy](https://www.speakeasy.com): ruled out because it is a commercial product -- [Stainless](https://www.stainless.com/): not available anymore (as of September 2026) +- [Stainless](https://www.stainless.com/): not available anymore (since May 2026) Commercial generators are not considered for multiple reasons, one of them being that this would make external contributions to the SDK more difficult. From 5c2b68bdebcd07d94442a439c51f3f2f374999c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcel=20Wien=C3=B6bst?= Date: Thu, 1 Oct 2026 08:57:09 +0200 Subject: [PATCH 3/3] update status --- adr/0004-openapi-generators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adr/0004-openapi-generators.md b/adr/0004-openapi-generators.md index 1efd0233..7f51fa3a 100644 --- a/adr/0004-openapi-generators.md +++ b/adr/0004-openapi-generators.md @@ -2,7 +2,7 @@ ## Status -proposed +agreed ## Context