feat(python-flask): add opt-in Connexion 3 support

Adds a new `useConnexion3` boolean generator option (default: false) to
the python-flask server generator, addressing #17303. Connexion 3 has
been out since 2023, but requirements.mustache explicitly pinned
`connexion<=2.14.2` and `Flask==2.1.1` to avoid it, blocking users from
picking up newer Flask/Werkzeug (one comment on the issue specifically
cited this as blocking a CVE fix in werkzeug). The maintainer has
repeatedly invited a contribution on the thread since Dec 2023, and
several community members had already prototyped working fixes in the
comments.

Kept as an opt-in flag rather than a default bump, following this
repo's existing convention for breaking generator-output changes
(useJackson3, useSpringBoot3/4).

What changes under the flag, and why:
- requirements.mustache / setup.mustache: swap the Connexion 2/Flask
  2.1.1 pins for `connexion[flask,swagger-ui,uvicorn]>=3.3.0,<4.0.0` +
  `Flask>=2.2.0,<4.0.0`. The uvicorn extra is required because
  Connexion 3's `FlaskApp.run()` launches via uvicorn even for Flask
  apps -- confirmed by actually running the generated server, which
  fails at startup without it. The connexion floor is 3.3.0 (not just
  the first 3.0.0 release) because that's the only version we've
  actually run and verified, and it's also the first release with
  official Python 3.13/3.14 support per Connexion's own release notes.
  swagger-ui-bundle is bumped to >=1.1.0 to match the floor Connexion's
  own swagger-ui extra already silently requires.
- __main__.mustache: `connexion.App` -> `connexion.FlaskApp`, and the
  JSON encoder moves from a `Flask.json_encoder` attribute assignment
  (removed in v3) to a `Jsonifier(cls=...)` passed into `add_api()`.
- encoder.mustache: the generated `JSONEncoder` becomes a plain
  `json.JSONEncoder` subclass instead of extending Connexion 2's
  `FlaskJSONEncoder` (removed in v3); the `default()` body handling
  `Model.to_dict()` conversion is unchanged. Verified end-to-end (not
  just unit-level): patched a controller to return a real nested
  Pet/Category model instance, ran the actual generated server
  (uvicorn + Flask + Connexion 3) in Docker, and curled it -- got back
  correctly serialized JSON with attribute_map key translation intact
  (photo_urls -> photoUrls).
- __init__test.mustache: Connexion 3's `app.test_client()` returns an
  httpx/Starlette-based client, not Flask's WSGI test client -- so a
  small `_FlaskStyleTestClient`/`_FlaskStyleResponse` adapter is added
  to keep the existing `self.client.open(...)`/`self.assert200(...)`
  calling convention in controller_test.mustache working unchanged.
  Also drops `flask_testing.TestCase`, which is unmaintained since 2020
  and not Flask-3-compatible.
- test-requirements.mustache: drops the `Flask-Testing` pin under the
  flag, since Flask's own test client no longer needs it.
- CORS support (featureCORS): `flask_cors.CORS(app.app)` does not work
  under Connexion 3, because Connexion 3 wraps the Flask app in its own
  ASGI middleware stack and can route/short-circuit requests before
  they ever reach the inner WSGI app flask-cors is watching. Confirmed
  this was actually broken (zero Access-Control-* headers on a real
  request with an Origin header) before fixing it. Replaced with
  Connexion 3's own documented pattern --
  `app.add_middleware(CORSMiddleware, ...)` from
  `starlette.middleware.cors`, which comes for free as a connexion
  dependency, no separate package needed. flask-cors itself is no
  longer installed at all under useConnexion3. Reverified afterwards:
  Access-Control-Allow-Origin and Access-Control-Allow-Credentials both
  present on the response.

One unconditional (non-flag-gated) fix: controller.mustache swaps
`connexion.request.is_json`/`.get_json()` for Flask's own
`from flask import request`. Connexion 3's `connexion.request` is now a
Starlette Request and no longer exposes those Flask-specific methods.
Flask's own `request` object behaves identically under Connexion 2 and
3, so this is applied to both, and is a dependency-reduction as a side
effect. This is the only part of the diff that touches the existing
default sample output.

Also fixes #15062 (python-flask docs never explained *why* the
generator uses Connexion instead of vanilla Flask) via a `getHelp()`
override scoped to the Flask subclass, bundled in here since it's a
one-line addition to a PR already touching this generator's docs.
#21294 (operationId double-underscore breaking Connexion's resolver)
is a different root cause and is intentionally left for its own PR.

Security motivation, checked concretely rather than assumed: ran
pip-audit against the full resolved dependency tree for both paths.
v2 (current default, Flask==2.1.1/Werkzeug==2.2.3 as resolved): 10 real
CVEs across Flask+Werkzeug, including the exact one raised in the issue
thread (CVE-2024-34069) plus several more recent ones. v3
(useConnexion3, Flask==3.1.3/Werkzeug==3.1.8 as resolved): zero
vulnerabilities in any actual application dependency (the only
pip-audit hits in either scan are in pip/wheel themselves -- base image
tooling, not part of the app's declared dependencies, identical in both
scans).

Also surfaced, but explicitly NOT fixed here (separate, pre-existing,
unrelated to Connexion version -- reproduces even with
`useConnexion3: false`): generating python-flask through a config file
that has any `additionalProperties` block changes
`postProcessOperationsWithModels`'s `*/*`-consumes skip-marking
behavior for a couple of operations. Worth its own issue/investigation,
out of scope for this PR.

CI coverage: added bin/configs/python-flask-connexion3.yaml alongside
the existing bin/configs/python-flask.yaml, following the same pattern
used for other flag-gated variants (e.g. the *-jackson3.yaml configs),
so the "Samples up-to-date" job continuously verifies the new flag's
generated output.

Verification performed locally (this environment has no JDK/toolchain
installed, so all of the below ran inside Docker containers rather
than bare-metal):
- `mvn -pl modules/openapi-generator -am package` -- compiles clean.
- The full repo's CI "Unit tests" job command, run verbatim
  (`mvn clean --no-snapshot-updates --batch-mode --quiet --fail-at-end
  test`) across the whole reactor: 4493 tests run, 0 failures, 0
  errors, 7 skipped (confirmed via real surefire report files, not just
  the process exit code).
- Full `bin/generate-samples.sh` (all ~766 generators, no args) run
  twice in a row, mirroring the "Samples up-to-date" CI job exactly:
  zero diff outside the files intentionally touched by this change.
- Docs regenerated via `bin/utils/export_generator.sh python-flask`
  (not the full "Docs up-to-date" job across every generator, since
  this change only touches python-flask's own CliOptions/getHelp()).
- Built and ran the generated `useConnexion3: true` sample's own
  Dockerfile; server starts, serves `/v2/openapi.json`, returns a
  correct 401 on an auth-protected route without credentials, and
  correctly serializes a real returned model object end-to-end.
- Established a genuine Connexion-2 baseline in a separate
  Python-3.11 container (the generated Dockerfile's `python:3-alpine`
  base floats to Python 3.14, which breaks even the *unmodified* v2
  sample for unrelated reasons -- old Werkzeug's routing code hits a
  removed `ast.Str` API) to get a fair v2-vs-v3 comparison of the
  generated test suite. Both pass the same 8 real operations; the v3
  run's extra failures are either pre-existing test-fixture/spec bugs
  unrelated to Connexion version (confirmed present on the v2 baseline
  too), or a documented Connexion 3 behavior change where operations
  with multiple response content types require the handler to specify
  which one to return -- inherent to Connexion 3's stricter response
  handling for auto-generated placeholder stubs, not something
  template-level codegen changes can paper over.

Known gap, not fixed here: no CI job actually installs/runs the
generated python-flask server (the existing samples-python-server.yaml
workflow only covers python-aiohttp-srclayout) or the full "Docs
up-to-date" job across every generator, so ongoing regression coverage
for this flag's *runtime* behavior relies on the manual verification
above, not on CI.

Author: Shaun-3adesign

bin/configs/python-flask-connexion3.yaml

@@ -0,0 +1,6 @@
+generatorName: python-flask
+outputDir: samples/server/petstore/python-flask-connexion3
+inputSpec: modules/openapi-generator/src/test/resources/3_0/python-flask/petstore.yaml
+templateDir: modules/openapi-generator/src/main/resources/python-flask
+additionalProperties:
+  useConnexion3: "true"

docs/generators/python-flask.md

@@ -12,7 +12,7 @@ title: Documentation for the python-flask Generator
 | generator language | Python | |
 | generator language version | 3.5.2+ | |
 | generator default templating engine | mustache | |
-| helpTxt | Generates a Python server library using the Connexion project. By default, it will also generate service classes -- which you can disable with the `-Dnoservice` environment variable. | |
+| helpTxt | Generates a Python Flask server library using the Connexion project. Connexion is used (instead of hand-written Flask routes) because it maps operations in an OpenAPI/Swagger spec directly to Python functions, handling request routing, payload validation and parameter binding automatically. By default, it will also generate service classes -- which you can disable with the `-Dnoservice` environment variable. | |
 
 ## CONFIG OPTIONS
 These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
@@ -35,6 +35,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |sortModelPropertiesByRequiredFlag|Sort model properties to place required parameters before optional parameters.| |true|
 |sortParamsByRequiredFlag|Sort method arguments to place required parameters before optional parameters.| |true|
 |testsUsePythonSrcRoot|generates test under the pythonSrcRoot folder.| |false|
+|useConnexion3|Use Connexion 3.x instead of Connexion 2.x. This changes the pinned connexion/Flask/Flask-Testing dependency versions and switches the generated encoder, __main__ and test bootstrap code to Connexion 3's APIs. This is a breaking change to the generated output, so it defaults to false to preserve existing Connexion 2.x behavior.| |false|
 |useNose|use the nose test framework| |false|
 |usePythonSrcRootInImports|include pythonSrcRoot in import namespaces.| |false|
 

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/PythonFlaskConnexionServerCodegen.java

@@ -16,6 +16,7 @@
 
 package org.openapitools.codegen.languages;
 
+import org.openapitools.codegen.CliOption;
 import org.openapitools.codegen.SupportingFile;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -28,8 +29,40 @@
 public class PythonFlaskConnexionServerCodegen extends AbstractPythonConnexionServerCodegen {
     private final Logger LOGGER = LoggerFactory.getLogger(PythonFlaskConnexionServerCodegen.class);
 
+    public static final String USE_CONNEXION_3 = "useConnexion3";
+
+    protected boolean useConnexion3 = false;
+
     public PythonFlaskConnexionServerCodegen() {
         super("python-flask", false);
+
+        cliOptions.add(CliOption.newBoolean(USE_CONNEXION_3,
+                "Use Connexion 3.x instead of Connexion 2.x. This changes the pinned "
+                        + "connexion/Flask/Flask-Testing dependency versions and switches the "
+                        + "generated encoder, __main__ and test bootstrap code to Connexion 3's "
+                        + "APIs. This is a breaking change to the generated output, so it defaults "
+                        + "to false to preserve existing Connexion 2.x behavior.",
+                useConnexion3).defaultValue(Boolean.toString(useConnexion3)));
+    }
+
+    @Override
+    public void processOpts() {
+        super.processOpts();
+
+        if (additionalProperties.containsKey(USE_CONNEXION_3)) {
+            this.useConnexion3 = Boolean.parseBoolean(additionalProperties.get(USE_CONNEXION_3).toString());
+        }
+        additionalProperties.put(USE_CONNEXION_3, useConnexion3);
+    }
+
+    @Override
+    public String getHelp() {
+        return "Generates a Python Flask server library using the Connexion project. Connexion is "
+                + "used (instead of hand-written Flask routes) because it maps operations in an "
+                + "OpenAPI/Swagger spec directly to Python functions, handling request routing, "
+                + "payload validation and parameter binding automatically. By default, it will also "
+                + "generate service classes -- which you can disable with the `-Dnoservice` "
+                + "environment variable.";
     }
 
     /**

modules/openapi-generator/src/main/resources/python-flask/__init__test.mustache

@@ -1,6 +1,10 @@
 import logging
+{{#useConnexion3}}
+import unittest
+{{/useConnexion3}}
 
 import connexion
+{{^useConnexion3}}
 from flask_testing import TestCase
 
 from {{packageName}}.encoder import JSONEncoder
@@ -14,3 +18,54 @@ class BaseTestCase(TestCase):
         app.app.json_encoder = JSONEncoder
         app.add_api('openapi.yaml', pythonic_params=True)
         return app.app
+{{/useConnexion3}}
+{{#useConnexion3}}
+from connexion.jsonifier import Jsonifier
+
+from {{packageName}}.encoder import JSONEncoder
+
+
+class _FlaskStyleResponse:
+    """Adapts Connexion 3's httpx/Starlette test response to the
+    status_code/data attributes the generated controller tests expect."""
+
+    def __init__(self, response):
+        self._response = response
+        self.status_code = response.status_code
+        self.data = response.content
+
+
+class _FlaskStyleTestClient:
+    """Adapts Connexion 3's `app.test_client()` (httpx/Starlette-based) to
+    the Flask-style `.open(path, method=, headers=, data=, content_type=,
+    query_string=)` calling convention the generated controller tests use."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def open(self, path, method='GET', headers=None, data=None,
+              content_type=None, query_string=None):
+        headers = dict(headers or {})
+        if content_type:
+            headers['Content-Type'] = content_type
+        response = self._client.request(
+            method, path, headers=headers, content=data, params=query_string)
+        return _FlaskStyleResponse(response)
+
+
+class BaseTestCase(unittest.TestCase):
+
+    def setUp(self):
+        logging.getLogger('connexion.operation').setLevel('ERROR')
+        app = connexion.FlaskApp(__name__, specification_dir='../openapi/')
+        app.add_api('openapi.yaml', pythonic_params=True,
+                     jsonifier=Jsonifier(cls=JSONEncoder))
+        self._raw_client_cm = app.test_client()
+        self.client = _FlaskStyleTestClient(self._raw_client_cm.__enter__())
+
+    def tearDown(self):
+        self._raw_client_cm.__exit__(None, None, None)
+
+    def assert200(self, response, message=None):
+        self.assertEqual(200, response.status_code, message)
+{{/useConnexion3}}

modules/openapi-generator/src/main/resources/python-flask/__main__.mustache

@@ -1,25 +1,59 @@
 #!/usr/bin/env python3
 
 import connexion
+{{#useConnexion3}}
+from connexion.jsonifier import Jsonifier
+{{#featureCORS}}
+from connexion.middleware import MiddlewarePosition
+from starlette.middleware.cors import CORSMiddleware
+{{/featureCORS}}
+{{/useConnexion3}}
+{{^useConnexion3}}
 {{#featureCORS}}
 from flask_cors import CORS
 {{/featureCORS}}
+{{/useConnexion3}}
 
 from {{packageName}} import encoder
 
 
 def main():
+{{^useConnexion3}}
     app = connexion.App(__name__, specification_dir='./openapi/')
     app.app.json_encoder = encoder.JSONEncoder
     app.add_api('openapi.yaml',
                 arguments={'title': '{{appName}}'},
                 pythonic_params=True)
-
+{{/useConnexion3}}
+{{#useConnexion3}}
+    app = connexion.FlaskApp(__name__, specification_dir='./openapi/')
+{{#featureCORS}}
+    # add CORS support. Connexion 3 wraps the Flask app in its own ASGI
+    # middleware stack, so flask-cors (which only sees requests after
+    # they reach the inner WSGI app) never runs -- CORS has to be added
+    # as ASGI middleware instead.
+    app.add_middleware(
+        CORSMiddleware,
+        position=MiddlewarePosition.BEFORE_EXCEPTION,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+{{/featureCORS}}
+    app.add_api('openapi.yaml',
+                arguments={'title': '{{appName}}'},
+                pythonic_params=True,
+                jsonifier=Jsonifier(cls=encoder.JSONEncoder))
+{{/useConnexion3}}
+{{^useConnexion3}}
 {{#featureCORS}}
+
     # add CORS support
     CORS(app.app)
-
 {{/featureCORS}}
+{{/useConnexion3}}
+
     app.run(port={{serverPort}})
 
 

modules/openapi-generator/src/main/resources/python-flask/controller.mustache

@@ -1,4 +1,4 @@
-import connexion
+from flask import request
 from typing import Dict
 from typing import Tuple
 from typing import Union
@@ -73,41 +73,41 @@ def {{operationId}}({{#allParams}}{{^isBodyParam}}{{paramName}}{{/isBodyParam}}{
             {{^isPrimitiveType}}
                 {{^isFile}}
                     {{^isUuid}}
-    if connexion.request.is_json:
-        {{paramName}} = {{baseType}}{{^baseType}}{{#dataType}} {{.}}{{/dataType}}{{/baseType}}.from_dict(connexion.request.get_json())  # noqa: E501
+    if request.is_json:
+        {{paramName}} = {{baseType}}{{^baseType}}{{#dataType}} {{.}}{{/dataType}}{{/baseType}}.from_dict(request.get_json())  # noqa: E501
                     {{/isUuid}}
                 {{/isFile}}
             {{/isPrimitiveType}}
         {{/isContainer}}
         {{#isArray}}
             {{#items}}
                 {{#isDate}}
-    if connexion.request.is_json:
-        {{paramName}} = [util.deserialize_date(s) for s in connexion.request.get_json()]  # noqa: E501
+    if request.is_json:
+        {{paramName}} = [util.deserialize_date(s) for s in request.get_json()]  # noqa: E501
                 {{/isDate}}
                 {{#isDateTime}}
-    if connexion.request.is_json:
-        {{paramName}} = [util.deserialize_datetime(s) for s in connexion.request.get_json()]  # noqa: E501
+    if request.is_json:
+        {{paramName}} = [util.deserialize_datetime(s) for s in request.get_json()]  # noqa: E501
                 {{/isDateTime}}
                 {{#complexType}}
-    if connexion.request.is_json:
-        {{paramName}} = [{{complexType}}.from_dict(d) for d in connexion.request.get_json()]  # noqa: E501
+    if request.is_json:
+        {{paramName}} = [{{complexType}}.from_dict(d) for d in request.get_json()]  # noqa: E501
                 {{/complexType}}
             {{/items}}
         {{/isArray}}
         {{#isMap}}
             {{#items}}
                 {{#isDate}}
-    if connexion.request.is_json:
-        {{paramName}} = {k: util.deserialize_date(v) for k, v in connexion.request.get_json().items()}  # noqa: E501
+    if request.is_json:
+        {{paramName}} = {k: util.deserialize_date(v) for k, v in request.get_json().items()}  # noqa: E501
                 {{/isDate}}
                 {{#isDateTime}}
-    if connexion.request.is_json:
-        {{paramName}} = {k: util.deserialize_datetime(v) for k, v in connexion.request.get_json().items()}  # noqa: E501
+    if request.is_json:
+        {{paramName}} = {k: util.deserialize_datetime(v) for k, v in request.get_json().items()}  # noqa: E501
                 {{/isDateTime}}
                 {{#complexType}}
-    if connexion.request.is_json:
-        {{paramName}} = {k: {{baseType}}.from_dict(v) for k, v in connexion.request.get_json().items()}  # noqa: E501
+    if request.is_json:
+        {{paramName}} = {k: {{baseType}}.from_dict(v) for k, v in request.get_json().items()}  # noqa: E501
                 {{/complexType}}
             {{/items}}
         {{/isMap}}

modules/openapi-generator/src/main/resources/python-flask/encoder.mustache

@@ -1,3 +1,4 @@
+{{^useConnexion3}}
 from connexion.apps.flask_app import FlaskJSONEncoder
 
 from {{modelPackage}}.base_model import Model
@@ -17,3 +18,25 @@ class JSONEncoder(FlaskJSONEncoder):
                 dikt[attr] = value
             return dikt
         return FlaskJSONEncoder.default(self, o)
+{{/useConnexion3}}
+{{#useConnexion3}}
+import json
+
+from {{modelPackage}}.base_model import Model
+
+
+class JSONEncoder(json.JSONEncoder):
+    include_nulls = False
+
+    def default(self, o):
+        if isinstance(o, Model):
+            dikt = {}
+            for attr in o.openapi_types:
+                value = getattr(o, attr)
+                if value is None and not self.include_nulls:
+                    continue
+                attr = o.attribute_map[attr]
+                dikt[attr] = value
+            return dikt
+        return json.JSONEncoder.default(self, o)
+{{/useConnexion3}}

modules/openapi-generator/src/main/resources/python-flask/requirements.mustache

@@ -1,3 +1,4 @@
+{{^useConnexion3}}
 connexion[swagger-ui] >= 2.6.0; python_version>="3.6"
 # 2.3 is the last version that supports python 3.4-3.5
 connexion[swagger-ui] <= 2.3.0; python_version=="3.5" or python_version=="3.4"
@@ -7,11 +8,32 @@ connexion[swagger-ui] <= 2.14.2; python_version>"3.4"
 # we must peg werkzeug versions below to fix connexion
 # https://github.com/zalando/connexion/pull/1044
 werkzeug == 0.16.1; python_version=="3.5" or python_version=="3.4"
+{{/useConnexion3}}
+{{#useConnexion3}}
+# pinned to 3.3.0+ (not just the first 3.0.0 release) since that's the
+# earliest version verified to work with the Jsonifier/test_client setup
+# below, and the first to officially support Python 3.13/3.14
+connexion[flask,swagger-ui,uvicorn] >= 3.3.0,<4.0.0
+{{/useConnexion3}}
+{{^useConnexion3}}
 swagger-ui-bundle >= 0.0.2
+{{/useConnexion3}}
+{{#useConnexion3}}
+# connexion's own swagger-ui extra already requires this floor; pinned
+# explicitly here too so requirements.txt is self-documenting.
+swagger-ui-bundle >= 1.1.0
+{{/useConnexion3}}
 python_dateutil >= 2.6.0
+{{^useConnexion3}}
 {{#featureCORS}}
 # should support both Python 2 and Python 3
 flask-cors >= 3.0.10
 {{/featureCORS}}
+{{/useConnexion3}}
 setuptools >= 21.0.0
+{{^useConnexion3}}
 Flask == 2.1.1
+{{/useConnexion3}}
+{{#useConnexion3}}
+Flask >= 2.2.0,<4.0.0
+{{/useConnexion3}}

modules/openapi-generator/src/main/resources/python-flask/setup.mustache

@@ -12,8 +12,14 @@ VERSION = "{{packageVersion}}"
 # http://pypi.python.org/pypi/setuptools
 
 REQUIRES = [
+{{^useConnexion3}}
     "connexion>=2.0.2",
     "swagger-ui-bundle>=0.0.2",
+{{/useConnexion3}}
+{{#useConnexion3}}
+    "connexion[flask,uvicorn]>=3.3.0,<4.0.0",
+    "swagger-ui-bundle>=1.1.0",
+{{/useConnexion3}}
     "python_dateutil>=2.6.0"
 ]
 

modules/openapi-generator/src/main/resources/python-flask/test-requirements.mustache

@@ -10,4 +10,6 @@ pytest~=7.1.0
 pytest-cov>=2.8.1
 pytest-randomly>=1.2.3
 {{/useNose}}
+{{^useConnexion3}}
 Flask-Testing==0.8.1
+{{/useConnexion3}}