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/2] 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/2] 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.