`blackbull.openapi`¶

`blackbull.openapi` ¶

OpenAPI 3.1 spec generation + Swagger UI for BlackBull apps.

Walk the router and emit a minimal but valid OpenAPI document describing every HTTP route the app exposes. v1 covers what the router itself already knows:

paths, methods, scheme (HTTP-only — WebSocket routes are skipped);
path parameters with schemas derived from the converter (str / int / uuid / path);
handler docstring → summary / description;
a stub 200 response and, for write methods, a permissive requestBody: object placeholder.

What v1 does not do:

Request-body schemas — handlers do not yet declare body models, so the spec describes them as {"type": "object"}. Add a model layer (Pydantic or dataclass-with-schema) to lift this.
Security schemes — auth is application-defined here, so no global securitySchemes are emitted. Add per-app via the override parameter.
Tags / grouping — single flat list per path.

Usage from an app::

app = BlackBull()
app.enable_openapi(title='My API', version='1.0.0')

@app.route(path='/items/{item_id:int}')
async def get_item(item_id: int):
    return {'id': item_id}

After app.run() the spec is reachable at /openapi.json and the Swagger UI at /docs.

`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 a self-contained HTML page hosting Swagger UI pointed at spec_url.

blackbull.openapi¶