hayate-openapi

Hayate ecosystem: Start here · Production golden app · Tested compatibility

OpenAPI 3.1 generation for 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.4.x). The emitted OpenAPI 3.1.1 document passes openapi-spec-validator and feeds openapi-typescript 7.13 for end-to-end TypeScript types in a locked CI interoperability gate. The internal design memo (Japanese, per project convention) lives in DESIGN.md. Interactive Scalar docs, security schemes, multipart uploads, and strict inline typing are included. Release history is in CHANGELOG.md.

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 and interactive GET /docs are live; or emit statically:
#   python -m hayate_openapi main:app --title Bookstore --version 1.0.0

How it works

hayate-auth middleware can supply operation security automatically:

@app.get("/documents", auth.require_oauth_token("documents:read"))
async def documents(c):
    return c.json([])

OpenApi(
    app,
    title="API",
    version="1",
    security_schemes=auth.openapi_security_schemes(),
).register(app)

Use @describe(security=[]) for an explicitly public operation. For uploads, combine validated("form", schema, media_type="multipart/form-data") with binary_file() in a raw schema.

Schema conversion goes through a SchemaProvider protocol. msgspec and pydantic are auto-detected (guarded imports); a plain dict is taken as literal JSON Schema Draft 2020-12 and compiled once for runtime validation, including supported format checks such as UUID. The package depends on Hayate and jsonschema; msgspec and pydantic remain optional.

validated() supports the core's six targets: json, form, query, param, header, and cookie. The last four expand object properties into OpenAPI parameters. A param property must match a route parameter and overrides its generated schema while remaining required as OpenAPI mandates. Header schemas use the lowercase names exposed by Fetch; model aliases such as x-request-id keep a Python field name separate when needed. OpenAPI-reserved Accept, Content-Type, and Authorization header parameters are rejected instead of emitting fields the specification ignores.

TypeScript types, the recommended recipe:

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

The repository continuously runs the same flow against a representative app:

npm ci --ignore-scripts
scripts/check_interoperability.sh

The generator deliberately emits OpenAPI 3.1.1. Although OpenAPI 3.2.0 is published, openapi-typescript documents support for 3.0 and 3.1. Staying on 3.1.1 keeps validation, documentation, and typed client generation on one tested interoperability profile instead of claiming an unverified version bump. The private Node lock overrides vulnerable transitive parser/glob versions with patched releases; it is CI tooling and is not part of the Python distribution.

Interactive API reference

register() serves a 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:

# 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)

• 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.
• Cookie, Bearer, and OAuth 2.0 security requirements, including combined route middleware requirements.
• JSON, URL-encoded, and multipart request bodies, including binary file parts.

License

MIT