fix(python-blueplanet): render the spec into swagger.yaml instead of an empty file

KH
2h ago
+879-5

python-blueplanet generates app/openapi_server/swagger/swagger.yaml as an empty file. The petstore sample in samples/server/petstore/python-blueplanet has the same 0-byte file. __main__.py loads that file with app.add_api('swagger.yaml', ...), so the generated app has no spec to load.

The template swagger.mustache renders {{{swagger-yaml}}}. Nothing sets that key: it was replaced by openapi-yaml when OpenAPI 3.0 support was added (53597764c34), and this generator was added afterwards (#2184) with the old key. I didn't find an existing issue for this.

Changes

  • swagger.mustache renders {{{openapi-yaml}}}, the same key the python-flask, python-aiohttp and python-fastapi templates use. No Java change is needed: the key is already set for this generator.
  • A test checks that the generated swagger.yaml is not empty and contains openapi: and paths:. It fails without the change.
  • Regenerated the python-blueplanet sample. Only swagger.yaml changes, from 0 bytes to the petstore spec.

Verification

  • Python*Test / AbstractPython*Test pass.
  • bin/generate-samples.sh bin/configs/python*.yaml: the only diff is the blueplanet swagger.yaml above.
  • The generated swagger.yaml is a valid OpenAPI 3.0 document (checked with openapi-spec-validator).

Known limitation (not changed here)

The generated requirements.txt pins connexion == 1.1.15. Connexion 1.x only reads Swagger 2.0, so even with this fix the app still can't load the spec. With Python 3.11, connexion==1.1.15 and Flask 1.x, add_api('swagger.yaml') raises SwaggerValidationError: 'components', 'openapi', 'servers' do not match any of the regexes: '^x-'.

Making the generated app start would need moving python-blueplanet to Connexion 2.x, as python-flask uses. I'm happy to look into that in a follow-up if you'd like this generator kept working. I couldn't run the Blue Planet-specific dependencies (bp2hookutil, plansdk, twigjack) myself.

PR checklist

  • Read the contribution guidelines.
  • Run the following to build the project and update samples: 
    ./mvnw clean package || exit
./bin/generate-samples.sh ./bin/configs/*.yaml || exit
./bin/utils/export_docs_generators.sh || exit
    Regenerated all bin/configs/python*.yaml samples. Generator options and docs are unchanged.
  • If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

cc @cbornet @tomplus @krjakbrjak @fa0311 (Python technical committee)

Parts of this change were drafted with AI coding assistants (Devin, Claude Code) and reviewed and verified by me.

šŸ¤– Generated with Claude Code

Summary by cubic

Fixes python-blueplanet generating an empty swagger.yaml and pins Connexion to 2.x so generated apps can actually serve the OpenAPI 3.0 spec.

  • Switches swagger.mustache to render {{{openapi-yaml}}}; the old swagger-yaml key was renamed when OpenAPI 3.0 support was added, so the rendered file was 0 bytes.
  • Updates requirements.mustache and setup.mustache to the same Connexion 2.x constraints python-flask uses, since Connexion 1.x only reads Swagger/OpenAPI 2.0.
  • Adds tests that the generated swagger.yaml is non-empty and that Connexion is pinned within the 2.x range, and regenerates the petstore sample.