You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by "Kunal8954 (via GitHub)" <gi...@apache.org> on 2026/09/03 08:19:09 UTC
[PR] Fix: */* Accept header enum breaks generated Java client Javadoc [airflow]
Kunal8954 opened a new pull request, #72470:
URL: https://github.com/apache/airflow/pull/72470
## What
Changes the `Accept` header's OpenAPI schema on four endpoints from an
`enum` to `examples` list, and regenerates the OpenAPI spec accordingly.
## Why
The affected endpoints (`/dagSources/{dag_id}`, `/config`,
`/config/section/{section}/option/{option}`, and the task instance logs
endpoint) declare an `Accept` header with `json_schema_extra` listing
`application/json`, `text/plain` and `*/*` as an `enum`.
Some OpenAPI client generators - notably the Java generator - render
each `enum` value as its own named constant, with a Javadoc comment
built from that literal value. `*/*` contains `*/`, which prematurely
closes the generated Javadoc comment block, producing invalid Java
that fails to compile.
`enum` was also semantically wrong here: a real `Accept` header isn't
restricted to these exact literals (it can carry q-values, be
comma-separated, etc.), so `examples` is the more accurate keyword
regardless of the codegen bug.
## Changes
- `airflow-core/src/airflow/api_fastapi/common/headers.py`: `enum` →
`examples` for both `header_accept_json_or_text_depends` and
`header_accept_json_or_ndjson_depends`, plus a `description` and an
explanatory comment.
- `airflow-core/src/airflow/api_fastapi/core_api/openapi/v2-rest-api-generated.yaml`:
regenerated via `prek run generate-openapi-spec`.
- Added a newsfragment.
Fixes #72466
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_015kAvbZ6SeKgp6jbGcvpXSh
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Stop */* Accept header enum from breaking generated Java client Javadoc [airflow]
Posted by "jason810496 (via GitHub)" <gi...@apache.org>.
jason810496 commented on PR #72470:
URL: https://github.com/apache/airflow/pull/72470#issuecomment-5534463069
Closing as out of scope.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fix: */* Accept header enum breaks generated Java client Javadoc [airflow]
Posted by "Kunal8954 (via GitHub)" <gi...@apache.org>.
Kunal8954 commented on code in PR #72470:
URL: https://github.com/apache/airflow/pull/72470#discussion_r3925418985
##########
airflow-core/src/airflow/api_fastapi/common/headers.py:
##########
@@ -27,10 +27,18 @@ def header_accept_json_or_text_depends(
accept: Annotated[
str,
Header(
+ description="The response content type to negotiate for.",
+ # Listed as "examples", not "enum": a real Accept header isn't restricted to
+ # these exact literals (it may carry q-values, be comma-separated, etc.), and
+ # an "enum" containing the literal "*/*" gets rendered by some OpenAPI client
+ # generators (notably the Java generator) as a named enum constant whose
+ # generated Javadoc embeds that raw value - the "*/" inside it prematurely
+ # closes the Javadoc comment block and breaks the generated client.
+ # See https://github.com/apache/airflow/issues/72466
json_schema_extra={
"type": "string",
- "enum": [Mimetype.JSON, Mimetype.TEXT, Mimetype.ANY],
- }
+ "examples": [Mimetype.JSON, Mimetype.TEXT, Mimetype.ANY],
Review Comment:
Thanks for pushing on this - your question about testing with the actual
generator was the right one to ask, and it turned up something important.
1. Title updated (dropped the `fix:` prefix per the contributing guide).
2. Added a regression test (test_headers.py) for the schema-level change.
3. On your question about OpenAPI Generator - I generated *and compiled*
the Java client against the regenerated spec. Compilation still fails,
both before and after this PR's change. The actual break isn't the
enum constant I originally suspected - it's the `@param accept
(optional, default to */*)` Javadoc line, which comes from the header's
`default` value and is unescaped by openapi-generator's Java template
regardless of enum vs examples. I've filed the real bug upstream:
OpenAPITools/openapi-generator#<TBD>, and updated this PR's description
to reflect that it's a valid improvement (enum was the wrong keyword)
but doesn't fully close #72466 on its own.
Given that, happy to take direction on whether you'd rather this PR stay
scoped as-is (with an honest description) or be closed until there's an
upstream fix to point to - your call.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fix: */* Accept header enum breaks generated Java client Javadoc [airflow]
Posted by "Kunal8954 (via GitHub)" <gi...@apache.org>.
Kunal8954 commented on PR #72470:
URL: https://github.com/apache/airflow/pull/72470#issuecomment-5527348848
> By the way,
>
> 1. Regarding Airflow's PR title conventions, we usually just write a clear and concise description of what the PR does, rather than using prefixes like fix:, perf:, or feat:. I'd recommend checking out existing Airflow PR titles or the [contributing guide](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst) for reference. (CI will also check the PR title)
> 2. I think we should need a regression test for this
Thanks for both points.
1. Title updated - dropped the `fix:` prefix per the contributing guide
(checked contributing-docs/05_pull_requests.rst, which explicitly
says no conventional-commit prefixes, imperative mood only).
2. Added a regression test at
airflow-core/tests/unit/api_fastapi/common/test_headers.py covering
the schema (examples not enum, default preserved) and the header
negotiation behavior itself. 13 passed locally.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fix: */* Accept header enum breaks generated Java client Javadoc [airflow]
Posted by "ColtenOuO (via GitHub)" <gi...@apache.org>.
ColtenOuO commented on code in PR #72470:
URL: https://github.com/apache/airflow/pull/72470#discussion_r3924212554
##########
airflow-core/src/airflow/api_fastapi/common/headers.py:
##########
@@ -27,10 +27,18 @@ def header_accept_json_or_text_depends(
accept: Annotated[
str,
Header(
+ description="The response content type to negotiate for.",
+ # Listed as "examples", not "enum": a real Accept header isn't restricted to
+ # these exact literals (it may carry q-values, be comma-separated, etc.), and
+ # an "enum" containing the literal "*/*" gets rendered by some OpenAPI client
+ # generators (notably the Java generator) as a named enum constant whose
+ # generated Javadoc embeds that raw value - the "*/" inside it prematurely
+ # closes the Javadoc comment block and breaks the generated client.
+ # See https://github.com/apache/airflow/issues/72466
json_schema_extra={
"type": "string",
- "enum": [Mimetype.JSON, Mimetype.TEXT, Mimetype.ANY],
- }
+ "examples": [Mimetype.JSON, Mimetype.TEXT, Mimetype.ANY],
Review Comment:
Have you tested generating the Java client using OpenAPI Generator 7.22.0 (currently specified by Airflow)?
If the Mimetype.ANY parameter is present, the OpenAPI schema should still generate default: '*/*'.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fix: */* Accept header enum breaks generated Java client Javadoc [airflow]
Posted by "ColtenOuO (via GitHub)" <gi...@apache.org>.
ColtenOuO commented on PR #72470:
URL: https://github.com/apache/airflow/pull/72470#issuecomment-5525427736
By the way,
1. Regarding Airflow's PR title conventions, we usually just write a clear and concise description of what the PR does, rather than using prefixes like fix:, perf:, or feat:. I'd recommend checking out existing Airflow PR titles or the [contributing guide](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst) for reference. (CI will also check the PR title)
2. I think we should need a regression test for this
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fix: */* Accept header enum breaks generated Java client Javadoc [airflow]
Posted by "Kunal8954 (via GitHub)" <gi...@apache.org>.
Kunal8954 commented on code in PR #72470:
URL: https://github.com/apache/airflow/pull/72470#discussion_r3925418985
##########
airflow-core/src/airflow/api_fastapi/common/headers.py:
##########
@@ -27,10 +27,18 @@ def header_accept_json_or_text_depends(
accept: Annotated[
str,
Header(
+ description="The response content type to negotiate for.",
+ # Listed as "examples", not "enum": a real Accept header isn't restricted to
+ # these exact literals (it may carry q-values, be comma-separated, etc.), and
+ # an "enum" containing the literal "*/*" gets rendered by some OpenAPI client
+ # generators (notably the Java generator) as a named enum constant whose
+ # generated Javadoc embeds that raw value - the "*/" inside it prematurely
+ # closes the Javadoc comment block and breaks the generated client.
+ # See https://github.com/apache/airflow/issues/72466
json_schema_extra={
"type": "string",
- "enum": [Mimetype.JSON, Mimetype.TEXT, Mimetype.ANY],
- }
+ "examples": [Mimetype.JSON, Mimetype.TEXT, Mimetype.ANY],
Review Comment:
Good question - this turned up something important, so thanks for pushing on it.
I generated *and compiled* the Java client against the regenerated spec
(via the openapitools/openapi-generator-cli Docker image + a Maven
compile, not just the generation step). Compilation still fails, both
before and after this PR's enum->examples change.
The break isn't the enum constant I originally suspected - it's this
line in the generated Javadoc:
* @param accept (optional, default to */*)
That "default to */*" text comes straight from the header's `default`
value (which is correct and shouldn't change), and openapi-generator's
Java template embeds it raw with no comment-safe escaping - completely
independent of whether the schema says `enum` or `examples`. You can
confirm the default itself is unaffected: `default: '*/*'` is still
present in the regenerated spec.
I've filed the actual root cause upstream:
OpenAPITools/openapi-generator#<TBD>
So to directly answer your question: yes, tested with generator 7.25.0
(this repo's own pinned version) and it still doesn't compile - this PR
alone doesn't close that gap. I've updated the PR description to reflect
that honestly.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Stop */* Accept header enum from breaking generated Java client Javadoc [airflow]
Posted by "jason810496 (via GitHub)" <gi...@apache.org>.
jason810496 closed pull request #72470: Stop */* Accept header enum from breaking generated Java client Javadoc
URL: https://github.com/apache/airflow/pull/72470
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org