hayate-openapi 0.1.0__tar.gz

hayate_openapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuke Hayashi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hayate_openapi-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: hayate-openapi
+Version: 0.1.0
+Summary: OpenAPI 3.1 generation for hayate: routes from app.routes, schemas from your validators
+Keywords: hayate,openapi,json-schema,documentation
+Author: Yusuke Hayashi
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Requires-Dist: hayate>=0.8.0
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/hayatepy/hayate-openapi
+Description-Content-Type: text/markdown
+
+# hayate-openapi
+
+OpenAPI 3.1 generation for [hayate](https://github.com/hayatepy/hayate) —
+built from what your app already knows: routes from `app.routes`, request
+schemas from your validators, response schemas from one decorator. No magic
+inference, no schema-library lock-in.
+
+> **Status: alpha (0.1.x).** The emitted document passes the official
+> `openapi-spec-validator` and feeds `openapi-typescript` for end-to-end
+> TypeScript types. The internal design memo (Japanese, per project
+> convention) lives in [DESIGN.md](DESIGN.md).
+
+```python
+from hayate import Hayate
+from hayate_openapi import OpenApi, describe, validated
+import msgspec
+
+class BookIn(msgspec.Struct):
+    title: str
+
+app = Hayate()
+
+@app.post("/books", validated("json", BookIn))   # validator + schema tag in one
+@describe(status=201, summary="Create a book")
+async def create(c):
+    book = c.req.valid("json")     # BookIn instance — validation still runs
+    return c.json({"title": book.title}, status=201)
+
+OpenApi(app, title="Bookstore", version="1.0.0").register(app)
+# GET /openapi.json is live; or emit statically:
+#   python -m hayate_openapi main:app --title Bookstore --version 1.0.0
+```
+
+## How it works
+
+| Source | What it provides |
+|---|---|
+| `app.routes` (hayate ≥ 0.8) | every method + path, converted to OpenAPI templating (`:id` → `{id}`) |
+| `validated(target, T)` | request body / query / form schemas — a tagging wrapper around the core `validator`, behavior-identical |
+| `@describe(...)` | summary, tags, response schemas, operationId — all optional, all additive |
+
+Schema conversion goes through a `SchemaProvider` protocol. msgspec and
+pydantic are auto-detected (guarded imports); a plain dict is taken as
+literal JSON Schema. **The package itself depends only on hayate.**
+
+TypeScript types, the recommended recipe:
+
+```sh
+python -m hayate_openapi main:app --title API --version 1.0.0 -o openapi.json
+npx openapi-typescript openapi.json -o src/api-types.ts
+```
+
+Docs UI: serve the JSON and point any renderer at it — e.g. one line of
+[Scalar](https://github.com/scalar/scalar) or Redoc HTML. Nothing is bundled.
+
+## What is documented (and what is not)
+
+- Routes with real HTTP verbs; WebSocket routes and wildcard mounts
+  (`/api/auth/*`) are skipped.
+- Responses you declare. Undeclared operations get a bare 200 — the
+  generator never invents schemas.
+- Operations with a validator automatically document the 400
+  `application/problem+json` failure the framework actually returns.
+
+## License
+
+MIT

hayate_openapi-0.1.0/README.md

@@ -0,0 +1,67 @@
+# hayate-openapi
+
+OpenAPI 3.1 generation for [hayate](https://github.com/hayatepy/hayate) —
+built from what your app already knows: routes from `app.routes`, request
+schemas from your validators, response schemas from one decorator. No magic
+inference, no schema-library lock-in.
+
+> **Status: alpha (0.1.x).** The emitted document passes the official
+> `openapi-spec-validator` and feeds `openapi-typescript` for end-to-end
+> TypeScript types. The internal design memo (Japanese, per project
+> convention) lives in [DESIGN.md](DESIGN.md).
+
+```python
+from hayate import Hayate
+from hayate_openapi import OpenApi, describe, validated
+import msgspec
+
+class BookIn(msgspec.Struct):
+    title: str
+
+app = Hayate()
+
+@app.post("/books", validated("json", BookIn))   # validator + schema tag in one
+@describe(status=201, summary="Create a book")
+async def create(c):
+    book = c.req.valid("json")     # BookIn instance — validation still runs
+    return c.json({"title": book.title}, status=201)
+
+OpenApi(app, title="Bookstore", version="1.0.0").register(app)
+# GET /openapi.json is live; or emit statically:
+#   python -m hayate_openapi main:app --title Bookstore --version 1.0.0
+```
+
+## How it works
+
+| Source | What it provides |
+|---|---|
+| `app.routes` (hayate ≥ 0.8) | every method + path, converted to OpenAPI templating (`:id` → `{id}`) |
+| `validated(target, T)` | request body / query / form schemas — a tagging wrapper around the core `validator`, behavior-identical |
+| `@describe(...)` | summary, tags, response schemas, operationId — all optional, all additive |
+
+Schema conversion goes through a `SchemaProvider` protocol. msgspec and
+pydantic are auto-detected (guarded imports); a plain dict is taken as
+literal JSON Schema. **The package itself depends only on hayate.**
+
+TypeScript types, the recommended recipe:
+
+```sh
+python -m hayate_openapi main:app --title API --version 1.0.0 -o openapi.json
+npx openapi-typescript openapi.json -o src/api-types.ts
+```
+
+Docs UI: serve the JSON and point any renderer at it — e.g. one line of
+[Scalar](https://github.com/scalar/scalar) or Redoc HTML. Nothing is bundled.
+
+## What is documented (and what is not)
+
+- Routes with real HTTP verbs; WebSocket routes and wildcard mounts
+  (`/api/auth/*`) are skipped.
+- Responses you declare. Undeclared operations get a bare 200 — the
+  generator never invents schemas.
+- Operations with a validator automatically document the 400
+  `application/problem+json` failure the framework actually returns.
+
+## License
+
+MIT

hayate_openapi-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["uv_build>=0.9,<1"]
+build-backend = "uv_build"
+
+[project]
+name = "hayate-openapi"
+version = "0.1.0"
+description = "OpenAPI 3.1 generation for hayate: routes from app.routes, schemas from your validators"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Yusuke Hayashi" }]
+keywords = ["hayate", "openapi", "json-schema", "documentation"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Documentation",
+]
+dependencies = ["hayate>=0.8.0"]
+
+[project.urls]
+Repository = "https://github.com/hayatepy/hayate-openapi"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3",
+  "pytest-asyncio>=0.25",
+  "ruff>=0.9",
+  "msgspec>=0.18",
+  "pydantic>=2.9",
+  "openapi-spec-validator>=0.7",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]

hayate_openapi-0.1.0/src/hayate_openapi/__init__.py

@@ -0,0 +1,25 @@
+"""hayate-openapi: OpenAPI 3.1 from what your app already knows."""
+
+from .generate import OpenApi
+from .providers import (
+    MsgspecProvider,
+    PydanticProvider,
+    RawSchemaProvider,
+    SchemaProvider,
+    default_providers,
+)
+from .tags import describe, validated
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MsgspecProvider",
+    "OpenApi",
+    "PydanticProvider",
+    "RawSchemaProvider",
+    "SchemaProvider",
+    "__version__",
+    "default_providers",
+    "describe",
+    "validated",
+]

hayate_openapi-0.1.0/src/hayate_openapi/__main__.py

@@ -0,0 +1,44 @@
+"""CLI: python -m hayate_openapi app:app --title X --version 1.0 [-o out.json]"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import sys
+from pathlib import Path
+
+from .generate import OpenApi
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="python -m hayate_openapi",
+        description="Emit the OpenAPI 3.1 document for a hayate app.",
+    )
+    parser.add_argument("app", help="import target, e.g. 'main:app'")
+    parser.add_argument("--title", required=True)
+    parser.add_argument("--version", required=True)
+    parser.add_argument("--description")
+    parser.add_argument("-o", "--output", help="write here instead of stdout")
+    args = parser.parse_args(argv)
+
+    module_name, _, attribute = args.app.partition(":")
+    if not attribute:
+        parser.error("app must be 'module:attribute', e.g. 'main:app'")
+    sys.path.insert(0, str(Path.cwd()))
+    application = getattr(importlib.import_module(module_name), attribute)
+
+    document = OpenApi(
+        application, title=args.title, version=args.version, description=args.description
+    ).generate()
+    text = json.dumps(document, indent=2)
+    if args.output:
+        Path(args.output).write_text(text + "\n", encoding="utf-8")
+    else:
+        print(text)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hayate_openapi-0.1.0/src/hayate_openapi/generate.py

@@ -0,0 +1,195 @@
+"""The generator: walk ``app.routes``, merge the tags, emit OpenAPI 3.1.
+
+Everything here is a pure function of the app object — no I/O, no globals —
+so ``generate()`` is trivially testable and the mounted endpoint is just
+``c.json(generate())``.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from hayate import Context, Response
+
+from .providers import SchemaProvider, default_providers, resolve
+from .tags import OPENAPI_ATTR
+
+OPENAPI_VERSION = "3.1.1"
+
+_PARAM_RE = re.compile(r":(\w+)(\([^)]*\))?")
+# Only real HTTP verbs become operations; hayate's websocket routes use an
+# internal marker method and are not documentable in OpenAPI.
+_HTTP_METHODS = frozenset({"GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "TRACE"})
+
+
+def _convert_path(pattern: str) -> tuple[str, list[dict[str, Any]]] | None:
+    """URLPattern pathname -> (OpenAPI path, path parameters).
+
+    Wildcard patterns are not documentable operations; returns None for them.
+    """
+    if "*" in pattern:
+        return None
+    parameters: list[dict[str, Any]] = []
+
+    def replace(match: re.Match[str]) -> str:
+        name, regex = match.group(1), match.group(2)
+        schema: dict[str, Any] = {"type": "string"}
+        if regex:
+            schema["pattern"] = regex[1:-1]
+        parameters.append({"name": name, "in": "path", "required": True, "schema": schema})
+        return "{" + name + "}"
+
+    return _PARAM_RE.sub(replace, pattern), parameters
+
+
+def _operation_id(method: str, path: str) -> str:
+    slug = re.sub(r"[^a-zA-Z0-9]+", "_", path).strip("_") or "root"
+    return f"{method.lower()}_{slug}"
+
+
+class OpenApi:
+    def __init__(
+        self,
+        app: Any,
+        *,
+        title: str,
+        version: str,
+        description: str | None = None,
+        path: str = "/openapi.json",
+        providers: list[SchemaProvider] | None = None,
+    ) -> None:
+        self.app = app
+        self.title = title
+        self.version = version
+        self.description = description
+        self.path = path
+        self.providers = providers if providers is not None else default_providers()
+
+    # -- generation --------------------------------------------------------------------
+
+    def generate(self) -> dict[str, Any]:
+        paths: dict[str, dict[str, Any]] = {}
+        components: dict[str, Any] = {}
+
+        for route in self.app.routes:
+            if route.method not in _HTTP_METHODS:
+                continue
+            converted = _convert_path(route.pattern)
+            if converted is None:
+                continue
+            path, path_params = converted
+            operation = self._operation(route, path, path_params, components)
+            paths.setdefault(path, {})[route.method.lower()] = operation
+
+        document: dict[str, Any] = {
+            "openapi": OPENAPI_VERSION,
+            "info": {"title": self.title, "version": self.version},
+            "paths": paths,
+        }
+        if self.description is not None:
+            document["info"]["description"] = self.description
+        if components:
+            document["components"] = {"schemas": components}
+        return document
+
+    def _operation(
+        self,
+        route: Any,
+        path: str,
+        path_params: list[dict[str, Any]],
+        components: dict[str, Any],
+    ) -> dict[str, Any]:
+        meta = getattr(route.handler, OPENAPI_ATTR, {})
+        operation: dict[str, Any] = {
+            "operationId": meta.get("operation_id") or _operation_id(route.method, path),
+            "responses": {},
+        }
+        for key in ("summary", "description", "tags"):
+            if meta.get(key) is not None:
+                operation[key] = meta[key]
+        if meta.get("deprecated"):
+            operation["deprecated"] = True
+
+        parameters = list(path_params)
+        has_validator = False
+        for middleware in route.middleware:
+            tag = getattr(middleware, OPENAPI_ATTR, None)
+            if tag is None:
+                continue
+            has_validator = True
+            schema = self._register_schema(tag["type"], components)
+            target = tag["target"]
+            if target == "json":
+                operation["requestBody"] = {
+                    "required": True,
+                    "content": {"application/json": {"schema": schema}},
+                }
+            elif target == "form":
+                operation["requestBody"] = {
+                    "required": True,
+                    "content": {"application/x-www-form-urlencoded": {"schema": schema}},
+                }
+            else:  # query: expand an object schema into individual parameters
+                parameters.extend(self._query_parameters(schema, components))
+
+        if parameters:
+            operation["parameters"] = parameters
+
+        responses: dict[str, Any] = {}
+        for status, type_ in (meta.get("responses") or {}).items():
+            entry: dict[str, Any] = {"description": _status_text(status)}
+            if type_ is not None:
+                entry["content"] = {
+                    "application/json": {"schema": self._register_schema(type_, components)}
+                }
+            responses[str(status)] = entry
+        if not responses:
+            responses["200"] = {"description": "Successful response"}
+        if has_validator and "400" not in responses:
+            responses["400"] = {
+                "description": "Validation failed",
+                "content": {"application/problem+json": {"schema": {"type": "object"}}},
+            }
+        operation["responses"] = responses
+        return operation
+
+    def _register_schema(self, type_: Any, components: dict[str, Any]) -> dict[str, Any]:
+        provider = resolve(self.providers, type_)
+        schema, defs = provider.schema(type_)
+        components.update(defs)
+        return schema
+
+    def _query_parameters(
+        self, schema: dict[str, Any], components: dict[str, Any]
+    ) -> list[dict[str, Any]]:
+        resolved = self._deref(schema, components)
+        required = set(resolved.get("required", ()))
+        out = []
+        for name, prop in (resolved.get("properties") or {}).items():
+            out.append({"name": name, "in": "query", "required": name in required, "schema": prop})
+        return out
+
+    @staticmethod
+    def _deref(schema: dict[str, Any], components: dict[str, Any]) -> dict[str, Any]:
+        ref = schema.get("$ref", "")
+        if ref.startswith("#/components/schemas/"):
+            return components.get(ref.rsplit("/", 1)[1], {})
+        return schema
+
+    # -- mounting ----------------------------------------------------------------------
+
+    def register(self, app: Any) -> None:
+        async def openapi_handler(c: Context) -> Response:
+            return c.json(self.generate())
+
+        app.get(self.path)(openapi_handler)
+
+
+def _status_text(status: int) -> str:
+    import http
+
+    try:
+        return http.HTTPStatus(status).phrase
+    except ValueError:
+        return "Response"

hayate_openapi-0.1.0/src/hayate_openapi/providers.py

@@ -0,0 +1,109 @@
+"""Schema providers: type -> (JSON Schema 2020-12, referenced $defs).
+
+The chain is guarded-import autodetection (DESIGN §3.2): msgspec Structs,
+pydantic BaseModels, then raw dicts passed through untouched. Each provider
+also supplies the validation converter, so ``validated()`` needs no separate
+wiring.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Callable
+from typing import Any, Protocol
+
+
+class SchemaProvider(Protocol):
+    def supports(self, type_: Any) -> bool: ...
+
+    def schema(self, type_: Any) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Return (schema for the type, {name: definition} it references)."""
+        ...
+
+    def converter(self, type_: Any) -> Callable[[Any], Any]:
+        """A callable that validates/converts raw data (raises on failure)."""
+        ...
+
+
+_REF_PREFIX = "#/components/schemas/"
+
+
+class MsgspecProvider:
+    def __init__(self) -> None:
+        import msgspec
+
+        self._msgspec = msgspec
+
+    def supports(self, type_: Any) -> bool:
+        return isinstance(type_, type) and issubclass(type_, self._msgspec.Struct)
+
+    def schema(self, type_: Any) -> tuple[dict[str, Any], dict[str, Any]]:
+        schemas, components = self._msgspec.json.schema_components(
+            (type_,), ref_template=_REF_PREFIX + "{name}"
+        )
+        return schemas[0], dict(components)
+
+    def converter(self, type_: Any) -> Callable[[Any], Any]:
+        return lambda data: self._msgspec.convert(data, type_)
+
+
+class PydanticProvider:
+    def __init__(self) -> None:
+        from pydantic import TypeAdapter
+
+        self._adapter = TypeAdapter
+
+    def supports(self, type_: Any) -> bool:
+        try:
+            from pydantic import BaseModel
+        except ImportError:  # pragma: no cover - guarded twice
+            return False
+        return isinstance(type_, type) and issubclass(type_, BaseModel)
+
+    def schema(self, type_: Any) -> tuple[dict[str, Any], dict[str, Any]]:
+        raw = self._adapter(type_).json_schema(
+            ref_template=_REF_PREFIX + "{model}", mode="validation"
+        )
+        defs = raw.pop("$defs", {})
+        # The root model itself lands inline; hoist it so every model ref
+        # points into components uniformly.
+        name = type_.__name__
+        defs[name] = raw
+        return {"$ref": _REF_PREFIX + name}, defs
+
+    def converter(self, type_: Any) -> Callable[[Any], Any]:
+        adapter = self._adapter(type_)
+        return adapter.validate_python
+
+
+class RawSchemaProvider:
+    """A plain dict is taken as literal JSON Schema: documented, not enforced."""
+
+    def supports(self, type_: Any) -> bool:
+        return isinstance(type_, dict)
+
+    def schema(self, type_: Any) -> tuple[dict[str, Any], dict[str, Any]]:
+        return dict(type_), {}
+
+    def converter(self, type_: Any) -> Callable[[Any], Any]:
+        return lambda data: data
+
+
+def default_providers() -> list[SchemaProvider]:
+    chain: list[SchemaProvider] = []
+    with contextlib.suppress(ImportError):
+        chain.append(MsgspecProvider())
+    with contextlib.suppress(ImportError):
+        chain.append(PydanticProvider())
+    chain.append(RawSchemaProvider())
+    return chain
+
+
+def resolve(providers: list[SchemaProvider], type_: Any) -> SchemaProvider:
+    for provider in providers:
+        if provider.supports(type_):
+            return provider
+    raise TypeError(
+        f"no schema provider supports {type_!r}: install msgspec or pydantic, "
+        "or pass a raw JSON Schema dict"
+    )

hayate_openapi-0.1.0/src/hayate_openapi/tags.py

@@ -0,0 +1,66 @@
+"""The two annotation surfaces (DESIGN §3.1): ``validated`` wraps the core
+validator and tags the middleware with its type; ``describe`` tags the
+handler. Both are additive — untagged routes still document (thinly).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from hayate import Middleware, validator
+
+from .providers import SchemaProvider, default_providers, resolve
+
+OPENAPI_ATTR = "__openapi__"
+
+
+def validated(
+    target: str,
+    type_: Any,
+    *,
+    providers: list[SchemaProvider] | None = None,
+) -> Middleware:
+    """``hayate.validator`` plus an OpenAPI tag.
+
+    Validation behavior is identical to wiring the converter yourself; the
+    only addition is the ``__openapi__`` attribute the generator reads.
+    """
+    chain = providers if providers is not None else default_providers()
+    provider = resolve(chain, type_)
+    middleware = validator(target, provider.converter(type_))
+    middleware.__openapi__ = {"target": target, "type": type_}  # type: ignore[attr-defined]
+    return middleware
+
+
+def describe(
+    *,
+    summary: str | None = None,
+    description: str | None = None,
+    tags: list[str] | None = None,
+    status: int = 200,
+    response: Any | None = None,
+    responses: dict[int, Any] | None = None,
+    operation_id: str | None = None,
+    deprecated: bool = False,
+):
+    """Attach OpenAPI operation metadata to a handler (all fields optional).
+
+    ``response=T, status=201`` is sugar for ``responses={201: T}``; use
+    ``responses={404: None}`` for a schema-less documented status.
+    """
+    merged: dict[int, Any] = dict(responses or {})
+    if response is not None or (responses is None and status != 200):
+        merged.setdefault(status, response)
+
+    def wrap(handler):
+        handler.__openapi__ = {
+            "summary": summary,
+            "description": description,
+            "tags": tags,
+            "responses": merged,
+            "operation_id": operation_id,
+            "deprecated": deprecated,
+        }
+        return handler
+
+    return wrap