Add reusable component schemas to kaya-openapi

Operations could only inline schemas: the generated document had no
components section, so #/components/... references dangled. OpenAPIMixin
and generate_spec now accept a components mapping (merged verbatim into
the document) and kaya.openapi exports schema_ref() to build
#/components/schemas/<name> references. Component references are
validated at generation time and unknown ones raise ValueError.

packages/kaya-openapi/README.md

@@ -69,6 +69,48 @@ object, so any valid OpenAPI 3.1 construct can be used:
 `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`.
+
+```python
+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
 
 ```python
@@ -81,6 +123,7 @@ OpenAPIMixin(
     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)
 )
 ```