`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.

`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¶