hayate-openapi 0.2.0__tar.gz → 0.3.0__tar.gz

{hayate_openapi-0.2.0 → hayate_openapi-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hayate-openapi
-Version: 0.2.0
+Version: 0.3.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
@@ -27,12 +27,13 @@ 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.2.x).** The emitted document passes the official
+> **Status: alpha (0.3.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).
-> Security schemes, multipart uploads, and strict inline typing are included.
-> Release history is in [CHANGELOG.md](CHANGELOG.md).
+> Interactive Scalar docs, security schemes, multipart uploads, and strict
+> inline typing are included. Release history is in
+> [CHANGELOG.md](CHANGELOG.md).
 
 ```python
 from hayate import Hayate
@@ -51,7 +52,7 @@ async def create(c):
     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:
+# GET /openapi.json and interactive GET /docs are live; or emit statically:
 #   python -m hayate_openapi main:app --title Bookstore --version 1.0.0
 ```
 
@@ -93,8 +94,36 @@ 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.
+## Interactive API reference
+
+`register()` serves a [Scalar](https://github.com/scalar/scalar) API reference
+at `/docs` by default. It can execute requests, render schemas and security
+requirements, and generate client examples directly from the same OpenAPI 3.1
+document.
+
+The page has no inline JavaScript. It pins Scalar to an immutable version with
+Subresource Integrity and sends a restrictive Content Security Policy. Scalar
+is loaded from jsDelivr at browser time, while Scalar's telemetry, external
+client, sharing, deployment, MCP-generation, developer-tools, and AI-agent
+integrations are disabled by default. The Python package therefore keeps its
+single `hayate` dependency without sending the API document to another
+service. Disable the page or self-host the script when needed:
+
+```python
+# JSON only
+OpenApi(app, title="API", version="1", docs_path=None).register(app)
+
+# Same-origin, self-hosted Scalar bundle
+OpenApi(
+    app,
+    title="API",
+    version="1",
+    scalar_script_url="/assets/scalar.js",
+).register(app)
+```
+
+The OpenAPI JSON and docs routes are intentionally excluded from the generated
+application schema.
 
 ## What is documented (and what is not)
 

{hayate_openapi-0.2.0 → hayate_openapi-0.3.0}/README.md

@@ -5,12 +5,13 @@ 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.2.x).** The emitted document passes the official
+> **Status: alpha (0.3.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).
-> Security schemes, multipart uploads, and strict inline typing are included.
-> Release history is in [CHANGELOG.md](CHANGELOG.md).
+> Interactive Scalar docs, security schemes, multipart uploads, and strict
+> inline typing are included. Release history is in
+> [CHANGELOG.md](CHANGELOG.md).
 
 ```python
 from hayate import Hayate
@@ -29,7 +30,7 @@ async def create(c):
     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:
+# GET /openapi.json and interactive GET /docs are live; or emit statically:
 #   python -m hayate_openapi main:app --title Bookstore --version 1.0.0
 ```
 
@@ -71,8 +72,36 @@ 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.
+## Interactive API reference
+
+`register()` serves a [Scalar](https://github.com/scalar/scalar) API reference
+at `/docs` by default. It can execute requests, render schemas and security
+requirements, and generate client examples directly from the same OpenAPI 3.1
+document.
+
+The page has no inline JavaScript. It pins Scalar to an immutable version with
+Subresource Integrity and sends a restrictive Content Security Policy. Scalar
+is loaded from jsDelivr at browser time, while Scalar's telemetry, external
+client, sharing, deployment, MCP-generation, developer-tools, and AI-agent
+integrations are disabled by default. The Python package therefore keeps its
+single `hayate` dependency without sending the API document to another
+service. Disable the page or self-host the script when needed:
+
+```python
+# JSON only
+OpenApi(app, title="API", version="1", docs_path=None).register(app)
+
+# Same-origin, self-hosted Scalar bundle
+OpenApi(
+    app,
+    title="API",
+    version="1",
+    scalar_script_url="/assets/scalar.js",
+).register(app)
+```
+
+The OpenAPI JSON and docs routes are intentionally excluded from the generated
+application schema.
 
 ## What is documented (and what is not)
 

{hayate_openapi-0.2.0 → hayate_openapi-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "hayate-openapi"
-version = "0.2.0"
+version = "0.3.0"
 description = "OpenAPI 3.1 generation for hayate: routes from app.routes, schemas from your validators"
 readme = "README.md"
 requires-python = ">=3.12"

{hayate_openapi-0.2.0 → hayate_openapi-0.3.0}/src/hayate_openapi/__init__.py

@@ -17,7 +17,7 @@ from .security import (
 )
 from .tags import binary_file, describe, validated
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "MsgspecProvider",

{hayate_openapi-0.2.0 → hayate_openapi-0.3.0}/src/hayate_openapi/generate.py

@@ -7,9 +7,12 @@ so ``generate()`` is trivially testable and the mounted endpoint is just
 
 from __future__ import annotations
 
+import html
+import json
 import re
 from collections.abc import Mapping
 from typing import Any
+from urllib.parse import urlsplit
 
 from hayate import Context, Response
 
@@ -19,8 +22,12 @@ from .tags import OPENAPI_ATTR
 
 OPENAPI_VERSION = "3.1.1"
 
+_SCALAR_SCRIPT_URL = "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.63.0"
+_SCALAR_SCRIPT_INTEGRITY = "sha384-bnRzGcRYqM9jbXxeIbNDWWD8mNMY0p8qvmfAyfcT5S7/I6E7bsyLprA0uIP2gUu7"
+_OPENAPI_EXCLUDE_ATTR = "__hayate_openapi_exclude__"
 _PARAM_RE = re.compile(r":(\w+)(\([^)]*\))?")
 _PATH_TEMPLATE_PARAM_RE = re.compile(r"\{[^{}]+\}")
+_HTTPS_HOST_RE = re.compile(r"^[A-Za-z0-9.-]+$")
 # 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"})
@@ -60,15 +67,25 @@ class OpenApi:
         version: str,
         description: str | None = None,
         path: str = "/openapi.json",
+        docs_path: str | None = "/docs",
+        scalar_script_url: str = _SCALAR_SCRIPT_URL,
         providers: list[SchemaProvider] | None = None,
         security_schemes: Mapping[str, SecurityScheme] | None = None,
         security: list[SecurityRequirement] | None = None,
     ) -> None:
+        if docs_path is not None:
+            if not docs_path.startswith("/") or docs_path.startswith("//"):
+                raise ValueError("docs_path must be an absolute application path")
+            if docs_path == path:
+                raise ValueError("docs_path and path must be different")
         self.app = app
         self.title = title
         self.version = version
         self.description = description
         self.path = path
+        self.docs_path = docs_path
+        self.scalar_script_url = scalar_script_url
+        self._scalar_script_source = _script_source(scalar_script_url)
         self.providers = providers if providers is not None else default_providers()
         self.security_schemes = dict(security_schemes or {})
         self.security = security
@@ -82,6 +99,8 @@ class OpenApi:
         operation_ids: set[str] = set()
 
         for route in self.app.routes:
+            if getattr(route.handler, _OPENAPI_EXCLUDE_ATTR, False):
+                continue
             if route.method not in _HTTP_METHODS:
                 continue
             converted = _convert_path(route.pattern)
@@ -228,8 +247,106 @@ class OpenApi:
         async def openapi_handler(c: Context) -> Response:
             return c.json(self.generate())
 
+        setattr(openapi_handler, _OPENAPI_EXCLUDE_ATTR, True)
         app.get(self.path)(openapi_handler)
 
+        if self.docs_path is not None:
+
+            async def docs_handler(c: Context) -> Response:
+                return c.html(
+                    self._docs_html(),
+                    headers={
+                        "cache-control": "no-store",
+                        "content-security-policy": self._docs_csp(),
+                        "referrer-policy": "no-referrer",
+                        "x-content-type-options": "nosniff",
+                    },
+                )
+
+            setattr(docs_handler, _OPENAPI_EXCLUDE_ATTR, True)
+            app.get(self.docs_path)(docs_handler)
+
+    def _docs_html(self) -> str:
+        configuration = html.escape(
+            json.dumps(
+                {
+                    "url": self.path,
+                    "withDefaultFonts": False,
+                    "showDeveloperTools": "never",
+                    "hideClientButton": True,
+                    "agent": {"disabled": True},
+                    "mcp": {"disabled": True},
+                    "telemetry": False,
+                },
+                ensure_ascii=False,
+                separators=(",", ":"),
+            ),
+            quote=True,
+        )
+        script_url = html.escape(self.scalar_script_url, quote=True)
+        title = html.escape(self.title, quote=True)
+        integrity = ""
+        if self.scalar_script_url == _SCALAR_SCRIPT_URL:
+            integrity = (
+                f'\n      integrity="{_SCALAR_SCRIPT_INTEGRITY}"\n      crossorigin="anonymous"'
+            )
+        return f"""<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>{title} API reference</title>
+  </head>
+  <body>
+    <script
+      id="api-reference"
+      data-configuration="{configuration}"
+      src="{script_url}"{integrity}
+    ></script>
+    <noscript>Enable JavaScript to use the interactive API reference.</noscript>
+  </body>
+</html>
+"""
+
+    def _docs_csp(self) -> str:
+        return "; ".join(
+            (
+                "default-src 'none'",
+                f"script-src {self._scalar_script_source}",
+                "style-src 'unsafe-inline'",
+                "img-src data: https:",
+                "connect-src 'self' https:",
+                "font-src 'none'",
+                "object-src 'none'",
+                "base-uri 'none'",
+                "form-action 'none'",
+                "frame-ancestors 'none'",
+            )
+        )
+
+
+def _script_source(url: str) -> str:
+    if any(ord(character) < 0x20 or ord(character) == 0x7F for character in url):
+        raise ValueError("scalar_script_url must not contain control characters")
+    if url.startswith("/") and not url.startswith("//"):
+        return "'self'"
+
+    parsed = urlsplit(url)
+    if (
+        parsed.scheme != "https"
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.hostname is None
+        or _HTTPS_HOST_RE.fullmatch(parsed.hostname) is None
+    ):
+        raise ValueError("scalar_script_url must be root-relative or use an HTTPS origin")
+    try:
+        port = parsed.port
+    except ValueError as exc:
+        raise ValueError("scalar_script_url has an invalid port") from exc
+    suffix = f":{port}" if port is not None else ""
+    return f"https://{parsed.hostname}{suffix}"
+
 
 def _status_text(status: int) -> str:
     import http