kaya/packages/kaya-openapi

kaya-openapi

Automatic OpenAPI specification generation for the Kaya lightweight ASGI web framework.

The package provides an OpenAPIMixin that inspects a KayaApp's routing tree and serves:

• an OpenAPI 3.1 JSON document (default: GET /openapi.json)
• a Swagger UI page to browse it interactively (default: GET /docs)

Usage

from kaya.core import HttpContext, KayaApp
from kaya.openapi import OpenAPIMixin, operation

app = KayaApp(mixins=[OpenAPIMixin(title='My API', version='1.0.0')])


@app.GET('/users/${user_id:int}')
@operation(summary='Get a user',
           tags=['users'],
           responses={
               200: {'description': 'The user'},
               404: {'description': 'User not found'},
           })
async def get_user(ctx: HttpContext, user_id: int) -> None:
    ...

Run the app with any ASGI/RSGI server and open http://localhost:8000/docs.

How routes are mapped

• Static segments and parameters are converted to OpenAPI path templating:
  • /users/${user_id} → /users/{user_id} (string path parameter)
  • /users/${user_id:int} → /users/{user_id} (integer path parameter)
• Wildcard routes (*) are skipped: they cannot be expressed in OpenAPI path syntax.
• Websocket routes are skipped: OpenAPI does not model websockets.
• Method-agnostic routes (registered with app.route(path) without methods) are documented under all standard HTTP methods, since they respond to all of them.
• The mixin's own endpoints are excluded from the document unless include_self=True.

The document is generated on every request to the spec endpoint, so routes registered after the mixin is applied are always included.

Operation metadata

The @operation decorator attaches OpenAPI metadata to a route handler. All fragments are plain dicts merged verbatim into the generated operation object, so any valid OpenAPI 3.1 construct can be used:

@operation(summary='...',            # operation summary
           description='...',        # defaults to the handler docstring
           tags=['users'],
           operation_id='getUser',
           request_body={...},       # OpenAPI requestBody object
           responses={200: {...}},   # per-status-code response objects
           parameters=[...],         # extra/overriding parameter objects
           deprecated=False,
           hidden=False)             # exclude from the document

parameters entries whose name and in match an auto-generated path parameter override it; all others are appended.

Reusable schemas (components)

Schemas can be defined once and referenced from operation fragments: pass a components mapping to the mixin and use schema_ref in @operation.

from kaya.openapi import OpenAPIMixin, operation, schema_ref

USER = {
    'type': 'object',
    'required': ['id'],
    'properties': {'id': {'type': 'integer'}, 'name': {'type': 'string'}},
}
USER_PAGE = {
    'type': 'object',
    'properties': {'results': {'type': 'array', 'items': schema_ref('User')}},
}

app = KayaApp(mixins=[OpenAPIMixin(
    title='My API',
    version='1.0.0',
    components={'schemas': {'User': USER, 'UserPage': USER_PAGE}},
)])


@app.GET('/users')
@operation(summary='List users',
           responses={200: {
               'description': 'A page of users',
               'content': {'application/json': {'schema': schema_ref('UserPage')}},
           }})
async def list_users(ctx: HttpContext) -> None:
    ...

components is merged verbatim (as a copy) into the generated document under components, so Swagger UI lists the named schemas. Every #/components/<section>/<name> reference — in operations or between components — is validated when the document is generated: a missing section or entry raises ValueError. Reflected references (./other.json#/..., absolute URLs) are left alone.

Configuration

OpenAPIMixin(
    title='My API',                # info.title (required)
    version='1.0.0',               # info.version (required)
    description='',                # info.description
    spec_path='/openapi.json',     # where the JSON document is served
    docs_path='/docs',             # where Swagger UI is served
    servers=[{'url': 'https://api.example.com'}],
    openapi_version='3.1.0',
    include_self=False,            # include spec/docs endpoints in the document
    components=None,               # reusable OpenAPI components (e.g. schemas)
)

The document can also be generated programmatically without serving it:

from kaya.openapi import generate_spec

spec = generate_spec(app, title='My API', version='1.0.0')