📝 Document custom headers for JSONL and SSE streams

[Deadshot1831]

Pull Request

Discussion: N/A - docs-only clarification with tutorial test coverage.

Description

This PR documents how to add custom response headers to JSON Lines and SSE streaming endpoints.

FastAPI already documents the common pattern in Response Headers: use a Response parameter and mutate response.headers. This PR adds the streaming-specific caveat. For generator endpoints, setting a header inside the generator body is too late because FastAPI has already prepared the streaming response before the generator starts yielding data.

The examples use a dependency with a Response parameter to set the header before FastAPI creates the streaming response. Dependencies are resolved before the response is prepared, so the header is available at the correct point.

Changes:

• Add a JSON Lines tutorial section and runnable docs example for custom stream headers.
• Add an SSE tutorial section and runnable docs example for custom stream headers.
• Add tutorial tests that verify the custom header is present, the response media type is still correct, the stream body is produced, and OpenAPI keeps the expected streaming schema.

Validation

python -m pytest tests/test_tutorial/test_stream_json_lines tests/test_tutorial/test_server_sent_events tests/test_sse.py tests/test_stream_bare_type.py tests/test_stream_json_validation_error.py -q
52 passed

python -m ruff check docs_src/stream_json_lines/tutorial002_py310.py docs_src/server_sent_events/tutorial006_py310.py tests/test_tutorial/test_stream_json_lines/test_tutorial002.py tests/test_tutorial/test_server_sent_events/test_tutorial006.py
All checks passed

git diff --check

I did not run the full docs build locally because this venv does not have the full docs dependency group installed.

[codspeed-hq]

Merging this PR will not alter performance

✅ 20 untouched benchmarks

---

_{Comparing Deadshot1831:deadshot-sse-jsonl-tests-docs (a9b2d87) with master (1e60e32)¹}

Footnotes

1. No successful run was found on master (7cb06f3) during the generation of this report, so 1e60e32 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[github-actions]

📝 Docs preview

Last commit a9b2d87 at: https://b1ecfcaf.fastapitiangolo.pages.dev

Modified Pages

• https://b1ecfcaf.fastapitiangolo.pages.dev/tutorial/server-sent-events/ - (before)
• https://b1ecfcaf.fastapitiangolo.pages.dev/tutorial/stream-json-lines/ - (before)

[Deadshot1831]

a9b2d87
made the changes via this commit waiting for approval

[YuriiMotov]

@Deadshot1831, thanks!

Your version is technically precise, but it seems a bit hard to read, so I prepared an alternative version that might be simpler for newcomers.
Please, take a look or we can just leave it for Sebastian to decide.

[YuriiMotov]

Suggested change

	With an SSE stream, the *path operation function* is a generator. Calling it creates the generator, but the code inside the generator body doesn't run until the response is already streaming. So setting headers inside the generator body is too late for headers that need to be sent with the response.
	Instead, use a dependency that receives the `Response` parameter and sets the headers before the stream starts:
	{* ../../docs_src/server_sent_events/tutorial006_py310.py ln[1:33] hl[3:4,22:23,26:30] *}
	Dependencies run before FastAPI creates the streaming response, so FastAPI can copy those headers into the final SSE response.
	With an SSE stream, the *path operation function* is a generator. FastAPI starts the response before the body of that generator is executed. Because the response headers have already been sent, modifying the `Response` object inside the endpoint function has no effect.
	Instead, use a dependency that receives the `Response` parameter and sets the headers before the response starts:
	{* ../../docs_src/server_sent_events/tutorial006_py310.py ln[1:33] hl[3:4,22:23,26:30] *}
	Dependencies are resolved before FastAPI starts sending the response, so headers they set on the `Response` object are included in the outgoing response.