fireflyframework · ancongui · Sep 30, 2026 · Sep 30, 2026 · Sep 30, 2026 · Sep 30, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,45 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## v26.09.12 (2026-09-30)
+
+### Added
+
+- Documentation-only `@openapi_operation` and public operation, request body,
+  parameter, response and response-header metadata for manual handlers. Declare
+  optional bodies, multiple media types/statuses and exact response headers
+  without changing function signatures, request binding or response dispatch.
+- Public framework-neutral `RouteMetadata` supports offline generation without
+  application startup, service resolution or optional web dependencies.
+- OpenAPI security schemes, global requirements and per-operation overrides,
+  including explicit public operations. These declarations describe the contract;
+  they neither grant access nor enforce authentication or authorization.
+- Public custom Pydantic `schema_generator` and `create_app(openapi_generator=...)`
+  extension points for consumer schema policies and the served specification.
+
+### Fixed
+
+- Generate unions, discriminated unions, `Annotated` types, containers, recursive
+  models, UUIDs, enums and parameter constraints using Pydantic. Input schemas use
+  validation mode; response schemas use serialization mode, preserving aliases.
+- Resolve schema references and discriminator mappings across colliding model
+  names and differing input/output schemas. Repeated exports and reversed route
+  discovery produce deterministic documents.
+- Respect explicit operation IDs and mapping names, qualify inferred name
+  collisions, and reject duplicate explicit IDs or controller path/method pairs.
+- Inspect controller methods without evaluating custom descriptors or properties.
+
+### Upgrading
+
+- Existing decorators and runtime bindings retain their behavior. Explicit
+  responses replace the declared status, including framework validation errors;
+  `replace_responses=True` replaces the whole inferred response map. An explicit
+  `request_body=None` suppresses body inference and `security=[]` overrides global
+  requirements for that operation.
+- Richer inferred schemas and collision-qualified IDs intentionally change the
+  generated specification. Set an explicit unique name/operation ID for clients
+  that require a fixed identifier. See the web guide for complete examples.
+
 ## v26.09.11 (2026-09-30)
 
 ### Fixed

diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@
   <a href="https://github.com/fireflyframework"><img src="https://img.shields.io/badge/Firefly_Framework-official-ff6600?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyeiIvPjwvc3ZnPg==" alt="Firefly Framework"></a>
   <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12%2B-blue?logo=python&logoColor=white" alt="Python 3.12+"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green" alt="License: Apache 2.0"></a>
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-26.09.11-brightgreen" alt="Version: 26.09.11"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-26.09.12-brightgreen" alt="Version: 26.09.12"></a>
   <a href="https://mypy-lang.org/"><img src="https://img.shields.io/badge/type--checked-mypy%20strict-blue?logo=python&logoColor=white" alt="Type Checked: mypy strict"></a>
   <a href="https://docs.astral.sh/ruff/"><img src="https://img.shields.io/badge/code%20style-ruff-purple?logo=ruff&logoColor=white" alt="Code Style: Ruff"></a>
   <a href="#philosophy"><img src="https://img.shields.io/badge/async-first-brightgreen" alt="Async First"></a>
@@ -850,13 +850,13 @@ See **[`samples/lumen/`](samples/lumen/README.md)** for an end-to-end DDD micros
 
 ```bash
 # Install the latest release (uv)
-uv add "pyfly @ https://github.com/fireflyframework/fireflyframework-pyfly/releases/latest/download/pyfly-26.9.11-py3-none-any.whl"
+uv add "pyfly @ https://github.com/fireflyframework/fireflyframework-pyfly/releases/latest/download/pyfly-26.9.12-py3-none-any.whl"
 
 # Install with specific extras
-uv add "pyfly[web,data-relational,cache] @ https://github.com/fireflyframework/fireflyframework-pyfly/releases/latest/download/pyfly-26.9.11-py3-none-any.whl"
+uv add "pyfly[web,data-relational,cache] @ https://github.com/fireflyframework/fireflyframework-pyfly/releases/latest/download/pyfly-26.9.12-py3-none-any.whl"
 
 # Or with pip
-pip install "pyfly @ https://github.com/fireflyframework/fireflyframework-pyfly/releases/latest/download/pyfly-26.9.11-py3-none-any.whl"
+pip install "pyfly @ https://github.com/fireflyframework/fireflyframework-pyfly/releases/latest/download/pyfly-26.9.12-py3-none-any.whl"
 ```
 
 ### One-Line Install (CLI + Framework)
@@ -1184,6 +1184,7 @@ The git tag and human-readable display use the leading-zero form (`v26.05.01`);
 
 The full release history lives in **[CHANGELOG.md](CHANGELOG.md)** ([Keep a Changelog](https://keepachangelog.com/) format). Recent highlights:
 
+- **`v26.09.12`** (2026-09-30) — explicit offline OpenAPI contracts, rich Pydantic schemas, response/security overrides and stable operation IDs without changing handler behavior.
 - **`v26.09.11`** (2026-09-30) — scheduled-method discovery skips custom descriptors, avoiding Pydantic instance-field deprecation warnings.
 - **`v26.09.10`** (2026-09-29) — bounded JWKS rotation and HTTP responses, standalone OAuth acquisition, complete failed-start cleanup, substitutable observability and exact-byte webhook validation.
 - **`v26.09.09`** (2026-09-28) — a restarted context no longer resolves an interface through the previous run's binding (a second `start()` of the same context failed with a `KeyError`).

diff --git a/docs/cli.md b/docs/cli.md
@@ -775,7 +775,7 @@ Missing optional tools are shown with a `-` dash indicator (dimmed), while missi
 Verifies that PyFly itself is importable and displays the installed version:
 
 ```
-✓ pyfly v26.09.11
+✓ pyfly v26.09.12
 ```
 
 ### Summary

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -480,7 +480,7 @@ ______ ___.__._/ ____\  | ___.__.
 |   __// ____| |__|  |____/ ____|
 |__|   \/                 \/
 
-  PyFly v26.09.11 | Python 3.12.0
+  PyFly v26.09.12 | Python 3.12.0
 
 2026-01-15T10:30:00Z [info] starting_application  app=my-service version=0.1.0
 2026-01-15T10:30:00Z [info] no_active_profiles     message=No active profiles set, falling back to default

diff --git a/docs/installation.md b/docs/installation.md
@@ -513,7 +513,7 @@ PyFly Doctor
     ✓ mypy — Type checker
 
   PyFly packages:
-    ✓ pyfly v26.09.11
+    ✓ pyfly v26.09.12
 
   All checks passed!
 ```

diff --git a/docs/modules/core.md b/docs/modules/core.md
@@ -599,7 +599,7 @@ class BannerMode(enum.Enum):
 | Mode | Behavior |
 |---|---|
 | `TEXT` | Full ASCII art banner (default) with a framework version line. |
-| `MINIMAL` | Single line: `:: PyFly :: (v26.09.11)` |
+| `MINIMAL` | Single line: `:: PyFly :: (v26.09.12)` |
 | `OFF` | No banner output at all. |
 
 ### BannerPrinter Class
@@ -640,7 +640,7 @@ ______ ___.__._/ ____\  | ___.__.
 |   __// ____| |__|  |____/ ____|
 |__|   \/                 \/
 
-:: PyFly Framework :: (v26.09.11)
+:: PyFly Framework :: (v26.09.12)
 ```
 
 ### Custom Banner Files