woggioni/kaya
1
0
Fork 0
Code Actions Packages Releases Activity

Add kaya-openapi package for automatic OpenAPI spec generation

Browse Source 
- New packages/kaya-openapi with OpenAPIMixin, @operation decorator,
  and generate_spec() that walks the routing tree
- Enables kaya-core's Tree.register to expose the original handler
  callback as an instance attribute for metadata introspection
- Registers GET /openapi.json and GET /docs (Swagger UI) routes
- Supports  and  path parameters, docstring
  descriptions, @operation metadata, and excludes wildcard/WS routes
- Adds example/openapi.py, updates CI, README, and requirements
This commit is contained in:
woggioni
2026-07-25 09:20:19 +00:00
parent 87d1b0acb1
commit 9a68d10868
14 changed files with 762 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitea/workflows/build.yaml
+12
View File
@@ -48,6 +48,10 @@ jobs:
run: |
.venv/bin/python -m mypy -p kaya.oidc
.venv/bin/python -m unittest discover -s packages/kaya-oidc/tests
- name: Check kaya-openapi
run: |
.venv/bin/python -m mypy -p kaya.openapi
.venv/bin/python -m unittest discover -s packages/kaya-openapi/tests
- name: Publish kaya-core artifacts
env:
TWINE_REPOSITORY_URL: ${{ vars.PYPI_REGISTRY_URL }}
@@ -96,3 +100,11 @@ jobs:
run: |
.venv/bin/pyproject-build packages/kaya-oidc
.venv/bin/twine upload --repository gitea packages/kaya-oidc/dist/*.whl packages/kaya-oidc/dist/*.tar.gz
- name: Publish kaya-openapi artifacts
env:
TWINE_REPOSITORY_URL: ${{ vars.PYPI_REGISTRY_URL }}
TWINE_USERNAME: ${{ vars.PUBLISHER_USERNAME }}
TWINE_PASSWORD: ${{ secrets.PUBLISHER_TOKEN }}
run: |
.venv/bin/pyproject-build packages/kaya-openapi
.venv/bin/twine upload --repository gitea packages/kaya-openapi/dist/*.whl packages/kaya-openapi/dist/*.tar.gz
README.md
+5 -1
View File
@@ -12,6 +12,7 @@ This repository is a monorepo for the Kaya framework. The code is split into ind
- **kaya-session-redis** — Redis-backed session storage (`packages/kaya-session-redis/`)
- **kaya-session-memcache** — memcached-backed session storage (`packages/kaya-session-memcache/`)
- **kaya-oidc** — OpenID Connect authentication (`packages/kaya-oidc/`)
- **kaya-openapi** — automatic OpenAPI specification generation (`packages/kaya-openapi/`)
Additional `kaya-*` packages can be added as new directories under `packages/`.
@@ -26,7 +27,7 @@ pip install --index-url https://gitea.woggioni.net/api/packages/woggioni/pypi/si
Install the packages in development mode:
```bash
pip install -e packages/kaya-core -e packages/kaya-rsgi -e packages/kaya-session -e packages/kaya-session-redis -e packages/kaya-session-memcache -e packages/kaya-oidc
pip install -e packages/kaya-core -e packages/kaya-rsgi -e packages/kaya-session -e packages/kaya-session-redis -e packages/kaya-session-memcache -e packages/kaya-oidc -e packages/kaya-openapi
```
Run the example:
@@ -44,6 +45,7 @@ python -m unittest discover -s packages/kaya-session/tests
python -m unittest discover -s packages/kaya-session-redis/tests
python -m unittest discover -s packages/kaya-session-memcache/tests
python -m unittest discover -s packages/kaya-oidc/tests
python -m unittest discover -s packages/kaya-openapi/tests
```
## Static analysis
@@ -55,6 +57,7 @@ mypy -p kaya.session
mypy -p kaya.session.redis
mypy -p kaya.session.memcache
mypy -p kaya.oidc
mypy -p kaya.openapi
```
## Building packages
@@ -66,4 +69,5 @@ python -m build packages/kaya-session
python -m build packages/kaya-session-redis
python -m build packages/kaya-session-memcache
python -m build packages/kaya-oidc
python -m build packages/kaya-openapi
```
example/openapi.py
+32
View File
@@ -0,0 +1,32 @@
from kaya.core import HttpContext, KayaApp
from kaya.openapi import OpenAPIMixin, operation
app = KayaApp(mixins=[OpenAPIMixin(
title='Greeting API',
version='1.0.0',
description='Example API documented with kaya-openapi',
)])
@app.GET('/hello')
async def hello(ctx: HttpContext) -> None:
"""Say hello to the world."""
await ctx.send_str(200, 'Hello World')
@app.GET('/hello/${name}')
@operation(summary='Greet someone',
tags=['greetings'],
responses={200: {'description': 'A personalized greeting'}})
async def hello_name(ctx: HttpContext, name: str) -> None:
await ctx.send_str(200, f'Hello {name}')
@app.GET('/square/${x:int}')
@operation(summary='Compute the square of a number', tags=['math'])
async def square(ctx: HttpContext, x: int) -> None:
await ctx.send_str(200, str(x * x))
# serve with an ASGI/RSGI server, e.g.:
# granian --interface rsgi example.openapi:app
# then open http://localhost:8000/docs to browse the API
packages/kaya-core/src/kaya/core/_tree.py
+12 -1
View File
@@ -186,16 +186,27 @@ class Tree:
callback: Callable[[Context, Unpack[Any]], Awaitable[None]],
recursive: bool) -> None:
class Handler(PathHandler):
"""PathHandler created by :meth:`Tree.register`.
The original user callback is exposed through the ``callback``
attribute so that extensions (e.g. ``kaya-openapi``) can inspect
it for metadata such as docstrings or decorator attributes.
"""
callback: Callable[[Context, Unpack[Any]], Awaitable[None]]
async def handle_request(self, ctx: Context, captured: Matches) -> None:
args = Maybe.of_nullable(captured.path).map(lambda it: [it]).or_else([])
await callback(ctx, *args, **captured.kwargs)
await self.callback(ctx, *args, **captured.kwargs)
@property
def recursive(self) -> bool:
return recursive
handler = Handler()
# assigned as an instance attribute (not a class attribute) so that
# the function descriptor protocol does not turn it into a bound method
handler.callback = callback
self.add((p for p in PathIterator(path)), method, handler)
def find_node(self, path: Generator[str, None, None], method: HttpMethod = HttpMethod.GET) \
packages/kaya-openapi/README.md
+93
View File
@@ -0,0 +1,93 @@
# kaya-openapi
Automatic [OpenAPI](https://www.openapis.org/) specification generation for the
[Kaya](https://github.com/woggioni/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
```python
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:
```python
@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.
## Configuration
```python
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
)
```
The document can also be generated programmatically without serving it:
```python
from kaya.openapi import generate_spec
spec = generate_spec(app, title='My API', version='1.0.0')
```
packages/kaya-openapi/pyproject.toml
+56
View File
@@ -0,0 +1,56 @@
[build-system]
requires = ["setuptools>=61.0", "setuptools-scm>=8"]
build-backend = "setuptools.build_meta"
[project]
name = "kaya-openapi"
dynamic = ["version"]
authors = [
{ name="Walter Oggioni", email="oggioni.walter@gmail.com" },
]
description = "Automatic OpenAPI specification generation for the Kaya lightweight ASGI web framework"
readme = "README.md"
requires-python = ">=3.10"
license = "MIT"
classifiers = [
'Development Status :: 3 - Alpha',
'Topic :: Utilities',
'Intended Audience :: System Administrators',
'Intended Audience :: Developers',
'Environment :: Console',
'Programming Language :: Python :: 3',
]
dependencies = [
"kaya-core",
]
[project.optional-dependencies]
dev = [
"build", "mypy", "ipdb", "twine", "httpx", "httpx-ws"
]
[project.urls]
"Homepage" = "https://github.com/woggioni/kaya"
"Bug Tracker" = "https://github.com/woggioni/kaya/issues"
[tool.setuptools.packages.find]
where = ["src"]
namespaces = true
[tool.mypy]
python_version = "3.12"
disallow_untyped_defs = true
show_error_codes = true
no_implicit_optional = true
warn_return_any = true
warn_unused_ignores = true
exclude = ["scripts", "docs", "test"]
strict = true
[tool.setuptools_scm]
root = "../.."
version_file = "src/kaya/openapi/_version.py"
[tool.setuptools_scm.tag]
prefix = "release/"
packages/kaya-openapi/src/kaya/openapi/__init__.py
+10
View File
@@ -0,0 +1,10 @@
from ._metadata import operation
from ._mixin import OpenAPIMixin
from ._spec import generate_spec
__all__ = [
'OpenAPIMixin',
'generate_spec',
'operation',
]
packages/kaya-openapi/src/kaya/openapi/_metadata.py
+84
View File
@@ -0,0 +1,84 @@
from typing import Any, Awaitable, Callable, Mapping, Optional, Sequence, TypeVar
F = TypeVar('F', bound=Callable[..., Awaitable[None]])
METADATA_ATTR = '__kaya_openapi__'
#: Metadata attached to route handler functions by :func:`operation`.
#: Values are raw OpenAPI fragments (plain dicts) merged verbatim into the
#: generated operation object.
type OperationMetadata = Mapping[str, Any]
def operation(summary: Optional[str] = None,
description: Optional[str] = None,
tags: Optional[Sequence[str]] = None,
request_body: Optional[Mapping[str, Any]] = None,
responses: Optional[Mapping[int | str, Mapping[str, Any]]] = None,
parameters: Optional[Sequence[Mapping[str, Any]]] = None,
operation_id: Optional[str] = None,
deprecated: bool = False,
hidden: bool = False) -> Callable[[F], F]:
"""Attach OpenAPI metadata to a Kaya route handler.
The metadata is stored on the function itself and picked up by
:class:`~kaya.openapi.OpenAPIMixin` when generating the specification.
All schema fragments are plain dicts inserted verbatim into the generated
OpenAPI document, so any valid OpenAPI 3.1 construct can be used.
Example::
@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:
...
:param summary: short summary of the operation
:param description: longer description (defaults to the handler docstring)
:param tags: list of OpenAPI tags
:param request_body: OpenAPI ``requestBody`` object
:param responses: mapping of status code (or ``'default'``) to OpenAPI
response objects
:param parameters: extra OpenAPI parameter objects merged with the
auto-generated path parameters (entries whose ``name`` matches a path
parameter override the auto-generated one)
:param operation_id: explicit OpenAPI ``operationId``
:param deprecated: mark the operation as deprecated
:param hidden: exclude the operation from the generated specification
"""
def decorator(func: F) -> F:
metadata: dict[str, Any] = {}
if summary is not None:
metadata['summary'] = summary
if description is not None:
metadata['description'] = description
if tags is not None:
metadata['tags'] = list(tags)
if request_body is not None:
metadata['request_body'] = dict(request_body)
if responses is not None:
metadata['responses'] = {str(k): dict(v) for k, v in responses.items()}
if parameters is not None:
metadata['parameters'] = [dict(p) for p in parameters]
if operation_id is not None:
metadata['operation_id'] = operation_id
if deprecated:
metadata['deprecated'] = True
if hidden:
metadata['hidden'] = True
setattr(func, METADATA_ATTR, metadata)
return func
return decorator
def get_metadata(handler: Any) -> OperationMetadata:
"""Return the metadata attached by :func:`operation`, or an empty mapping."""
metadata = getattr(handler, METADATA_ATTR, None)
if isinstance(metadata, Mapping):
return metadata
return {}
packages/kaya-openapi/src/kaya/openapi/_mixin.py
+110
View File
@@ -0,0 +1,110 @@
import json
from html import escape
from typing import Any, Mapping, Optional, Sequence
from kaya.core import HttpContext, KayaApp, KayaMixin
from ._spec import generate_spec
_DOCS_PAGE = """<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>{title} - API documentation</title>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js" crossorigin></script>
<script>
window.onload = () => {{
window.ui = SwaggerUIBundle({{
url: '{spec_path}',
dom_id: '#swagger-ui',
}});
}};
</script>
</body>
</html>
"""
class OpenAPIMixin(KayaMixin):
"""Kaya mixin serving an auto-generated OpenAPI specification.
Registers two routes on the app:
- ``spec_path`` (default ``/openapi.json``): the OpenAPI document,
generated on each request from the application's routing tree so that
routes registered after the mixin are always included.
- ``docs_path`` (default ``/docs``): a Swagger UI page rendering the
specification (assets are loaded from a CDN).
Routes are converted as follows:
- ``${name}`` path segments become ``{name}`` string path parameters,
``${name:int}`` become integer path parameters;
- wildcard (``*``) and websocket routes are skipped, since they cannot be
expressed in OpenAPI;
- method-agnostic routes (registered with ``app.route(path)``) are
documented under all standard HTTP methods;
- the mixin's own routes are excluded unless ``include_self`` is true.
Use :func:`~kaya.openapi.operation` to attach summaries, tags, request
bodies and response schemas to individual handlers; the handler docstring
is used as the operation description when no explicit one is given.
Example::
openapi = OpenAPIMixin(title='My API', version='1.0.0')
app = KayaApp(mixins=[openapi])
@app.GET('/users/${user_id:int}')
@operation(summary='Get a user', tags=['users'])
async def get_user(ctx: HttpContext, user_id: int) -> None:
...
"""
def __init__(self,
title: str,
version: str,
description: str = '',
spec_path: str = '/openapi.json',
docs_path: str = '/docs',
servers: Optional[Sequence[Mapping[str, Any]]] = None,
openapi_version: str = '3.1.0',
include_self: bool = False) -> None:
self._title = title
self._version = version
self._description = description
self._spec_path = spec_path
self._docs_path = docs_path
self._servers = servers
self._openapi_version = openapi_version
self._include_self = include_self
def apply(self, app: KayaApp) -> None:
@app.GET(self._spec_path)
async def openapi_spec(ctx: HttpContext) -> None:
spec = self.generate_spec(app)
await ctx.send_str(200,
json.dumps(spec, indent=2),
{'Content-Type': 'application/json'})
@app.GET(self._docs_path)
async def openapi_docs(ctx: HttpContext) -> None:
page = _DOCS_PAGE.format(title=escape(self._title), spec_path=self._spec_path)
await ctx.send_str(200, page, {'Content-Type': 'text/html; charset=utf-8'})
def generate_spec(self, app: KayaApp) -> Mapping[str, Any]:
"""Generate the OpenAPI document for ``app`` (also used by the
``spec_path`` endpoint on every request)."""
exclude_paths = frozenset() if self._include_self else frozenset((self._spec_path, self._docs_path))
return generate_spec(app,
title=self._title,
version=self._version,
description=self._description,
servers=self._servers,
exclude_paths=exclude_paths,
openapi_version=self._openapi_version)
packages/kaya-openapi/src/kaya/openapi/_spec.py
+177
View File
@@ -0,0 +1,177 @@
from copy import deepcopy
from dataclasses import dataclass
from inspect import getdoc
from typing import AbstractSet, Any, Mapping, Optional, Sequence
from kaya.core import HttpMethod, KayaApp
from kaya.core._path_handler import PathHandler
from kaya.core._path_matcher import GlobMatcher, IntMatcher, Node, PathMatcher, StrMatcher
from ._metadata import get_metadata
#: HTTP methods documented for method-agnostic routes
#: (registered with ``app.route(path)`` without explicit methods).
STANDARD_METHODS: Sequence[HttpMethod] = (
HttpMethod.GET,
HttpMethod.PUT,
HttpMethod.POST,
HttpMethod.DELETE,
HttpMethod.OPTIONS,
HttpMethod.HEAD,
HttpMethod.PATCH,
)
@dataclass
class _Route:
raw_path: str
openapi_path: str
method: Optional[HttpMethod]
params: Sequence[Mapping[str, Any]]
handlers: Sequence[PathHandler]
def _walk(node: Node | PathMatcher,
raw_path: str,
openapi_path: str,
params: Sequence[Mapping[str, Any]],
routes: list[_Route]) -> None:
if node.handlers:
routes.append(_Route(raw_path or '/', openapi_path or '/', None, params, list(node.handlers)))
for key, child in node.children.items():
if isinstance(key, HttpMethod):
if key is not HttpMethod.WS and child.handlers:
routes.append(_Route(raw_path or '/', openapi_path or '/', key, params, list(child.handlers)))
else:
_walk(child, f'{raw_path}/{key}', f'{openapi_path}/{key}', params, routes)
for matcher in node.path_matchers:
if isinstance(matcher, GlobMatcher):
# Wildcard routes cannot be expressed in OpenAPI path syntax
continue
if isinstance(matcher, IntMatcher):
raw_segment = f'${{{matcher.name}:int}}'
schema: Mapping[str, Any] = {'type': 'integer'}
elif isinstance(matcher, StrMatcher):
raw_segment = f'${{{matcher.name}}}'
schema = {'type': 'string'}
else:
continue
param: dict[str, Any] = {
'name': matcher.name,
'in': 'path',
'required': True,
'schema': dict(schema),
}
_walk(matcher,
f'{raw_path}/{raw_segment}',
f'{openapi_path}/{{{matcher.name}}}',
(*params, param),
routes)
def _merge_parameters(params: Sequence[Mapping[str, Any]],
extra: Any) -> list[Mapping[str, Any]]:
merged: list[Mapping[str, Any]] = [dict(p) for p in params]
if not isinstance(extra, Sequence) or isinstance(extra, (str, bytes)):
return merged
for candidate in extra:
if not isinstance(candidate, Mapping):
continue
for i, existing in enumerate(merged):
if existing.get('name') == candidate.get('name') and existing.get('in') == candidate.get('in'):
merged[i] = candidate
break
else:
merged.append(candidate)
return merged
def _build_operation(params: Sequence[Mapping[str, Any]],
handler: PathHandler) -> Optional[dict[str, Any]]:
callback = getattr(handler, 'callback', None)
metadata = get_metadata(callback) if callback is not None else {}
if metadata.get('hidden'):
return None
operation: dict[str, Any] = {}
operation_id = metadata.get('operation_id')
if operation_id is not None:
operation['operationId'] = operation_id
summary = metadata.get('summary')
if summary is not None:
operation['summary'] = summary
description = metadata.get('description')
if description is None and callback is not None:
description = getdoc(callback)
if description is not None:
operation['description'] = description
tags = metadata.get('tags')
if tags is not None:
operation['tags'] = tags
if metadata.get('deprecated'):
operation['deprecated'] = True
parameters = _merge_parameters(params, metadata.get('parameters'))
if parameters:
operation['parameters'] = parameters
request_body = metadata.get('request_body')
if request_body is not None:
operation['requestBody'] = request_body
responses = metadata.get('responses')
operation['responses'] = responses if responses is not None else {
'default': {'description': 'Successful response'},
}
return operation
def generate_spec(app: KayaApp,
title: str,
version: str,
description: str = '',
servers: Optional[Sequence[Mapping[str, Any]]] = None,
exclude_paths: AbstractSet[str] = frozenset(),
openapi_version: str = '3.1.0') -> Mapping[str, Any]:
"""Generate an OpenAPI specification document from a :class:`KayaApp`.
The application's routing tree is walked and every route is converted to
an OpenAPI path item:
- static segments and ``${name}`` / ``${name:int}`` parameters are mapped
to OpenAPI path templating (``{name}``);
- wildcard (``*``) and websocket routes are skipped;
- method-agnostic routes are documented under all standard HTTP methods;
- routes whose Kaya path is in ``exclude_paths`` are skipped.
:param app: the application to inspect
:param title: value of ``info.title``
:param version: value of ``info.version``
:param description: value of ``info.description``
:param servers: list of OpenAPI server objects
:param exclude_paths: Kaya paths (e.g. ``/openapi.json``) to omit
:param openapi_version: OpenAPI version to declare
:return: the OpenAPI document as a JSON-serializable mapping
"""
routes: list[_Route] = []
_walk(app._tree.root, '', '', (), routes)
paths: dict[str, dict[str, Any]] = {}
for route in sorted(routes, key=lambda it: it.openapi_path):
if route.raw_path in exclude_paths or not route.handlers:
continue
operation = _build_operation(route.params, route.handlers[0])
if operation is None:
continue
path_item = paths.setdefault(route.openapi_path, {})
methods = STANDARD_METHODS if route.method is None else (route.method,)
for method in methods:
path_item[method.value.lower()] = deepcopy(operation)
info: dict[str, Any] = {'title': title, 'version': version}
if description:
info['description'] = description
spec: dict[str, Any] = {
'openapi': openapi_version,
'info': info,
'paths': paths,
}
if servers:
spec['servers'] = [dict(server) for server in servers]
return spec
packages/kaya-openapi/src/kaya/openapi/py.typed
View File
packages/kaya-openapi/tests/test_openapi.py
+167
View File
@@ -0,0 +1,167 @@
import json
import unittest
from typing import Any, Mapping, Sequence
import httpx
from pwo import async_test
from kaya.core import HttpContext, HttpMethod, KayaApp, WebSocket
from kaya.openapi import OpenAPIMixin, operation
class OpenAPITest(unittest.TestCase):
app: KayaApp
def setUp(self) -> None:
self.app = KayaApp(mixins=[OpenAPIMixin(title='Test API', version='1.2.3')])
@self.app.GET('/hello')
async def hello(ctx: HttpContext) -> None:
"""Say hello."""
await ctx.send_str(200, 'Hello World!')
@self.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:
await ctx.send_str(200, str(user_id))
@self.app.POST('/users/${name}')
async def create_user(ctx: HttpContext, name: str) -> None:
await ctx.send_str(201, name)
@self.app.route('/ping')
async def ping(ctx: HttpContext) -> None:
await ctx.send_str(200, 'pong')
@self.app.GET('/files/*', recursive=True)
async def serve_file(ctx: HttpContext, path: Sequence[str]) -> None:
await ctx.send_str(200, '/'.join(path))
@self.app.GET('/internal/health')
@operation(hidden=True)
async def health(ctx: HttpContext) -> None:
await ctx.send_str(200, 'ok')
@self.app.websocket('/echo')
async def echo(ws: WebSocket) -> None:
await ws.accept()
await ws.close()
async def _get_spec(self) -> Mapping[str, Any]:
transport = httpx.ASGITransport(app=self.app)
async with httpx.AsyncClient(transport=transport, base_url='http://127.0.0.1:80') as client:
response = await client.get('/openapi.json')
self.assertEqual(200, response.status_code)
self.assertEqual('application/json', response.headers['Content-Type'])
return json.loads(response.text)
@async_test
async def test_spec_endpoint(self) -> None:
spec = await self._get_spec()
self.assertEqual('3.1.0', spec['openapi'])
self.assertEqual({'title': 'Test API', 'version': '1.2.3'}, spec['info'])
self.assertIn('paths', spec)
@async_test
async def test_static_route_with_docstring(self) -> None:
spec = await self._get_spec()
hello = spec['paths']['/hello']['get']
self.assertEqual('Say hello.', hello['description'])
self.assertIn('responses', hello)
@async_test
async def test_int_path_parameter(self) -> None:
spec = await self._get_spec()
operation = spec['paths']['/users/{user_id}']['get']
self.assertEqual('Get a user', operation['summary'])
self.assertEqual(['users'], operation['tags'])
self.assertEqual({
'200': {'description': 'The user'},
'404': {'description': 'User not found'},
}, operation['responses'])
self.assertEqual(
[{'name': 'user_id', 'in': 'path', 'required': True, 'schema': {'type': 'integer'}}],
operation['parameters'])
@async_test
async def test_str_path_parameter(self) -> None:
spec = await self._get_spec()
operation = spec['paths']['/users/{name}']['post']
self.assertEqual(
[{'name': 'name', 'in': 'path', 'required': True, 'schema': {'type': 'string'}}],
operation['parameters'])
@async_test
async def test_method_agnostic_route(self) -> None:
spec = await self._get_spec()
path_item = spec['paths']['/ping']
for method in ('get', 'put', 'post', 'delete', 'options', 'head', 'patch'):
self.assertIn(method, path_item)
@async_test
async def test_excluded_routes(self) -> None:
spec = await self._get_spec()
paths = spec['paths']
# wildcard routes cannot be expressed in OpenAPI
self.assertNotIn('/files/*', paths)
self.assertFalse(any('files' in path for path in paths))
# websocket routes are not part of OpenAPI
self.assertNotIn('/echo', paths)
# hidden operations are skipped
self.assertNotIn('/internal/health', paths)
# the mixin's own endpoints are excluded by default
self.assertNotIn('/openapi.json', paths)
self.assertNotIn('/docs', paths)
@async_test
async def test_docs_endpoint(self) -> None:
transport = httpx.ASGITransport(app=self.app)
async with httpx.AsyncClient(transport=transport, base_url='http://127.0.0.1:80') as client:
response = await client.get('/docs')
self.assertEqual(200, response.status_code)
self.assertEqual('text/html; charset=utf-8', response.headers['Content-Type'])
self.assertIn('swagger-ui', response.text)
self.assertIn('/openapi.json', response.text)
@async_test
async def test_late_registered_routes_are_included(self) -> None:
@self.app.GET('/late')
async def late(ctx: HttpContext) -> None:
await ctx.send_str(200, 'late')
spec = await self._get_spec()
self.assertIn('/late', spec['paths'])
@async_test
async def test_custom_paths_and_self_inclusion(self) -> None:
app = KayaApp(mixins=[OpenAPIMixin(title='Custom',
version='0.1.0',
spec_path='/spec.json',
docs_path='/swagger',
include_self=True)])
@app.route('/items/${item_id:int}', HttpMethod.DELETE)
async def delete_item(ctx: HttpContext, item_id: int) -> None:
await ctx.send_empty(204)
transport = httpx.ASGITransport(app=app)
async with httpx.AsyncClient(transport=transport, base_url='http://127.0.0.1:80') as client:
response = await client.get('/spec.json')
self.assertEqual(200, response.status_code)
spec = json.loads(response.text)
self.assertIn('delete', spec['paths']['/items/{item_id}'])
self.assertIn('/spec.json', spec['paths'])
self.assertIn('/swagger', spec['paths'])
response = await client.get('/swagger')
self.assertEqual(200, response.status_code)
self.assertIn('/spec.json', response.text)
if __name__ == '__main__':
unittest.main()
requirements-dev.in
+1
View File
@@ -4,6 +4,7 @@ kaya-session @ file:./packages/kaya-session
kaya-session-redis @ file:./packages/kaya-session-redis
kaya-session-memcache @ file:./packages/kaya-session-memcache
kaya-oidc @ file:./packages/kaya-oidc
kaya-openapi @ file:./packages/kaya-openapi
build
fakeredis
mypy
requirements-dev.txt
+3
View File
@@ -90,10 +90,13 @@ file:./packages/kaya-core
# via
# -r requirements-dev.in
# kaya-oidc
# kaya-openapi
# kaya-rsgi
# kaya-session
file:./packages/kaya-oidc
# via -r requirements-dev.in
file:./packages/kaya-openapi
# via -r requirements-dev.in
file:./packages/kaya-rsgi
# via -r requirements-dev.in
file:./packages/kaya-session