`blackbull.openapi`¶

`blackbull.openapi` ¶

OpenAPI generation from registered routes.

Handler docstrings become summary/description. Dataclass annotations provide body schemas; security requires explicit configuration. Supply overrides for contracts not expressed by annotations.

`OpenAPIExtension` ¶

Bases: Extension

Mount an OpenAPI 3.1 spec endpoint and Swagger UI on a BlackBull app.

Accepts the same arguments as BlackBull.enable_openapi. Two construction styles are supported, following the framework's init_app(app) extension convention:

Eager — wire on construction.¶

OpenAPIExtension(app, title='My API', version='1.0.0')

Deferred — useful when the app is configured elsewhere.¶

ext = OpenAPIExtension(title='My API', version='1.0.0') ext.init_app(app)

After init_app:

app.extensions['openapi'] is self — collaborators can read the configured title/version/spec_path from it.
Two GET routes are registered: spec_path (JSON) and docs_path (HTML host for Swagger UI), the latter skipped when docs_path is None.
Both routes are flagged __blackbull_openapi_internal__ so the spec doesn't include itself.

`init_app(app)` ¶

Wire the spec + docs routes onto app through the public API.

`generate_spec(app, *, title='BlackBull API', version='0.1.0', description=None)` ¶

Walk app's router and return a dict matching OpenAPI 3.1.

The dict is JSON-serialisable. Pass it through json.dumps (or JSONResponse) on the spec route.

`swagger_ui_html(spec_url, title='BlackBull API — Swagger UI')` ¶

Return Swagger UI HTML for spec_url, loading assets from a CDN.

blackbull.openapi¶