fast-asyncapidoc 0.1.0__tar.gz

fast_asyncapidoc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qingyiwebt
+
+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.

fast_asyncapidoc-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: fast-asyncapidoc
+Version: 0.1.0
+Summary: Generate AsyncAPI 3 documentation for FastAPI WebSocket endpoints
+Keywords: asyncapi,documentation,fastapi,pydantic,websocket
+Author: qingyiwebt
+Author-email: qingyiwebt <qingyiweb@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: fastapi>=0.100,<1
+Requires-Dist: pydantic>=2,<3
+Requires-Dist: pyyaml>=6 ; extra == 'yaml'
+Requires-Python: >=3.10
+Project-URL: Documentation, https://github.com/qingyiwebt/fast-asyncapidoc#readme
+Project-URL: Homepage, https://github.com/qingyiwebt/fast-asyncapidoc
+Project-URL: Issues, https://github.com/qingyiwebt/fast-asyncapidoc/issues
+Project-URL: Repository, https://github.com/qingyiwebt/fast-asyncapidoc
+Provides-Extra: yaml
+Description-Content-Type: text/markdown
+
+# fast-asyncapidoc
+
+[简体中文](https://github.com/qingyiwebt/fast-asyncapidoc/blob/main/README.zh-CN.md)
+
+Generate [AsyncAPI 3.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0)
+documentation for [FastAPI](https://fastapi.tiangolo.com/) WebSocket endpoints
+using [Pydantic v2](https://docs.pydantic.dev/latest/).
+
+## Features
+
+- Describe WebSocket messages with repeatable `@asyncapi` decorators.
+- Generate AsyncAPI channels, operations, messages, and Pydantic schemas.
+- Document request/reply, receive-only, and server-push interactions.
+- Discover routes from direct FastAPI routes, routers, prefixes, and nested routers.
+- Mount the generated document at a JSON endpoint or export it as a Python `dict`.
+- Optionally serialize the document as YAML.
+- Keep endpoint functions unchanged, including their FastAPI dependency signatures.
+
+## Requirements
+
+- Python 3.10 or newer
+- FastAPI `>=0.100,<1`
+- Pydantic `>=2,<3`
+
+## Installation
+
+Install the package with uv:
+
+```bash
+uv add fast-asyncapidoc
+```
+
+Install optional YAML support when needed:
+
+```bash
+uv add "fast-asyncapidoc[yaml]"
+```
+
+## Quick start
+
+```python
+from fastapi import APIRouter, FastAPI, WebSocket
+from pydantic import BaseModel
+
+from fast_asyncapidoc import AsyncAPIDoc, asyncapi
+
+
+class ControlRequest(BaseModel):
+    command: str
+
+
+class ControlSuccess(BaseModel):
+    accepted: bool
+
+
+class ControlFailure(BaseModel):
+    error: str
+
+
+class ServerNotice(BaseModel):
+    message: str
+
+
+router = APIRouter()
+
+
+@router.websocket("/control")
+@asyncapi(
+    input=ControlRequest,
+    output=ControlSuccess,
+    operation_id="control.request_reply",
+    summary="Handle a control request",
+)
+@asyncapi(
+    input=ControlRequest,
+    outputs=[ControlSuccess, ControlFailure],
+    operation_id="control.result",
+)
+@asyncapi(
+    input=ControlRequest,
+    operation_id="control.receive_only",
+)
+@asyncapi(
+    output=ServerNotice,
+    operation_id="control.server_notice",
+)
+async def control(websocket: WebSocket) -> None:
+    await websocket.accept()
+    await websocket.close()
+
+
+app = FastAPI()
+app.include_router(router, prefix="/api")
+
+asyncapi_doc = AsyncAPIDoc(
+    app,
+    title="Control API",
+    version="1.0.0",
+    description="WebSocket API documentation",
+    servers={
+        "development": {
+            "host": "localhost:8000",
+            "protocol": "ws",
+        }
+    },
+)
+asyncapi_doc.mount("/asyncapi.json")
+```
+
+The generated document is available at `GET /asyncapi.json` and can also be
+obtained directly:
+
+```python
+document: dict = asyncapi_doc.generate()
+```
+
+## Decorator semantics
+
+`@asyncapi` accepts either a singular or plural form for each direction:
+
+```python
+@asyncapi(input=Request)
+@asyncapi(inputs=[RequestA, RequestB])
+@asyncapi(output=Response)
+@asyncapi(outputs=[Success, Failure])
+```
+
+The supported combinations are:
+
+| Inputs | Outputs | AsyncAPI operation |
+| --- | --- | --- |
+| One or more | None | `action: receive`, without `reply` |
+| One or more | One or more | `action: receive`, with `reply` |
+| None | One or more | `action: send`, for server push |
+
+An empty declaration is invalid. `input` and `inputs` cannot be used together,
+and the same applies to `output` and `outputs`.
+
+The decorator supports the following operation metadata:
+
+- `operation_id`: explicit key in the AsyncAPI `operations` map.
+- `title`, `summary`, `description`: operation documentation.
+- `tags`: operation grouping tags.
+
+The message payload schema is generated from each Pydantic model's
+`model_json_schema()` output. The package documents message contracts; it does
+not parse, validate, or transform runtime WebSocket frames.
+
+## YAML export
+
+After installing the `yaml` extra:
+
+```python
+yaml_document = asyncapi_doc.to_yaml()
+```
+
+## Development
+
+This repository uses uv for dependency management and builds:
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv build
+```
+
+## Links
+
+- [AsyncAPI 3.0 specification](https://www.asyncapi.com/docs/reference/specification/v3.0.0)
+- [FastAPI WebSockets](https://fastapi.tiangolo.com/advanced/websockets/)
+- [Pydantic](https://docs.pydantic.dev/latest/)
+- [uv](https://docs.astral.sh/uv/)
+- [Repository](https://github.com/qingyiwebt/fast-asyncapidoc)
+
+## License
+
+[MIT License](LICENSE)

fast_asyncapidoc-0.1.0/README.md

@@ -0,0 +1,179 @@
+# fast-asyncapidoc
+
+[简体中文](https://github.com/qingyiwebt/fast-asyncapidoc/blob/main/README.zh-CN.md)
+
+Generate [AsyncAPI 3.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0)
+documentation for [FastAPI](https://fastapi.tiangolo.com/) WebSocket endpoints
+using [Pydantic v2](https://docs.pydantic.dev/latest/).
+
+## Features
+
+- Describe WebSocket messages with repeatable `@asyncapi` decorators.
+- Generate AsyncAPI channels, operations, messages, and Pydantic schemas.
+- Document request/reply, receive-only, and server-push interactions.
+- Discover routes from direct FastAPI routes, routers, prefixes, and nested routers.
+- Mount the generated document at a JSON endpoint or export it as a Python `dict`.
+- Optionally serialize the document as YAML.
+- Keep endpoint functions unchanged, including their FastAPI dependency signatures.
+
+## Requirements
+
+- Python 3.10 or newer
+- FastAPI `>=0.100,<1`
+- Pydantic `>=2,<3`
+
+## Installation
+
+Install the package with uv:
+
+```bash
+uv add fast-asyncapidoc
+```
+
+Install optional YAML support when needed:
+
+```bash
+uv add "fast-asyncapidoc[yaml]"
+```
+
+## Quick start
+
+```python
+from fastapi import APIRouter, FastAPI, WebSocket
+from pydantic import BaseModel
+
+from fast_asyncapidoc import AsyncAPIDoc, asyncapi
+
+
+class ControlRequest(BaseModel):
+    command: str
+
+
+class ControlSuccess(BaseModel):
+    accepted: bool
+
+
+class ControlFailure(BaseModel):
+    error: str
+
+
+class ServerNotice(BaseModel):
+    message: str
+
+
+router = APIRouter()
+
+
+@router.websocket("/control")
+@asyncapi(
+    input=ControlRequest,
+    output=ControlSuccess,
+    operation_id="control.request_reply",
+    summary="Handle a control request",
+)
+@asyncapi(
+    input=ControlRequest,
+    outputs=[ControlSuccess, ControlFailure],
+    operation_id="control.result",
+)
+@asyncapi(
+    input=ControlRequest,
+    operation_id="control.receive_only",
+)
+@asyncapi(
+    output=ServerNotice,
+    operation_id="control.server_notice",
+)
+async def control(websocket: WebSocket) -> None:
+    await websocket.accept()
+    await websocket.close()
+
+
+app = FastAPI()
+app.include_router(router, prefix="/api")
+
+asyncapi_doc = AsyncAPIDoc(
+    app,
+    title="Control API",
+    version="1.0.0",
+    description="WebSocket API documentation",
+    servers={
+        "development": {
+            "host": "localhost:8000",
+            "protocol": "ws",
+        }
+    },
+)
+asyncapi_doc.mount("/asyncapi.json")
+```
+
+The generated document is available at `GET /asyncapi.json` and can also be
+obtained directly:
+
+```python
+document: dict = asyncapi_doc.generate()
+```
+
+## Decorator semantics
+
+`@asyncapi` accepts either a singular or plural form for each direction:
+
+```python
+@asyncapi(input=Request)
+@asyncapi(inputs=[RequestA, RequestB])
+@asyncapi(output=Response)
+@asyncapi(outputs=[Success, Failure])
+```
+
+The supported combinations are:
+
+| Inputs | Outputs | AsyncAPI operation |
+| --- | --- | --- |
+| One or more | None | `action: receive`, without `reply` |
+| One or more | One or more | `action: receive`, with `reply` |
+| None | One or more | `action: send`, for server push |
+
+An empty declaration is invalid. `input` and `inputs` cannot be used together,
+and the same applies to `output` and `outputs`.
+
+The decorator supports the following operation metadata:
+
+- `operation_id`: explicit key in the AsyncAPI `operations` map.
+- `title`, `summary`, `description`: operation documentation.
+- `tags`: operation grouping tags.
+
+The message payload schema is generated from each Pydantic model's
+`model_json_schema()` output. The package documents message contracts; it does
+not parse, validate, or transform runtime WebSocket frames.
+
+## YAML export
+
+After installing the `yaml` extra:
+
+```python
+yaml_document = asyncapi_doc.to_yaml()
+```
+
+## Development
+
+This repository uses uv for dependency management and builds:
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv build
+```
+
+## Links
+
+- [AsyncAPI 3.0 specification](https://www.asyncapi.com/docs/reference/specification/v3.0.0)
+- [FastAPI WebSockets](https://fastapi.tiangolo.com/advanced/websockets/)
+- [Pydantic](https://docs.pydantic.dev/latest/)
+- [uv](https://docs.astral.sh/uv/)
+- [Repository](https://github.com/qingyiwebt/fast-asyncapidoc)
+
+## License
+
+[MIT License](LICENSE)

fast_asyncapidoc-0.1.0/README.zh-CN.md

@@ -0,0 +1,179 @@
+# fast-asyncapidoc
+
+[English](README.md)
+
+使用 [Pydantic v2](https://docs.pydantic.dev/latest/) 模型，为
+[FastAPI](https://fastapi.tiangolo.com/) WebSocket endpoint 生成
+[AsyncAPI 3.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0)
+文档。
+
+## 特性
+
+- 使用可重复的 `@asyncapi` 装饰器描述 WebSocket 消息。
+- 自动生成 AsyncAPI channels、operations、messages 和 Pydantic schemas。
+- 支持请求/响应、只接收消息和服务器主动推送。
+- 支持直接注册的 WebSocket、APIRouter、路由前缀和嵌套路由。
+- 可挂载 JSON 文档路由，也可直接导出 Python `dict`。
+- 可选导出 YAML 文档。
+- 不包装 endpoint，不影响 FastAPI 依赖注入和函数签名。
+
+## 环境要求
+
+- Python 3.10 或更高版本
+- FastAPI `>=0.100,<1`
+- Pydantic `>=2,<3`
+
+## 安装
+
+使用 uv 安装：
+
+```bash
+uv add fast-asyncapidoc
+```
+
+需要 YAML 支持时安装可选依赖：
+
+```bash
+uv add "fast-asyncapidoc[yaml]"
+```
+
+## 快速开始
+
+```python
+from fastapi import APIRouter, FastAPI, WebSocket
+from pydantic import BaseModel
+
+from fast_asyncapidoc import AsyncAPIDoc, asyncapi
+
+
+class ControlRequest(BaseModel):
+    command: str
+
+
+class ControlSuccess(BaseModel):
+    accepted: bool
+
+
+class ControlFailure(BaseModel):
+    error: str
+
+
+class ServerNotice(BaseModel):
+    message: str
+
+
+router = APIRouter()
+
+
+@router.websocket("/control")
+@asyncapi(
+    input=ControlRequest,
+    output=ControlSuccess,
+    operation_id="control.request_reply",
+    summary="处理控制请求",
+)
+@asyncapi(
+    input=ControlRequest,
+    outputs=[ControlSuccess, ControlFailure],
+    operation_id="control.result",
+)
+@asyncapi(
+    input=ControlRequest,
+    operation_id="control.receive_only",
+)
+@asyncapi(
+    output=ServerNotice,
+    operation_id="control.server_notice",
+)
+async def control(websocket: WebSocket) -> None:
+    await websocket.accept()
+    await websocket.close()
+
+
+app = FastAPI()
+app.include_router(router, prefix="/api")
+
+asyncapi_doc = AsyncAPIDoc(
+    app,
+    title="Control API",
+    version="1.0.0",
+    description="WebSocket API 文档",
+    servers={
+        "development": {
+            "host": "localhost:8000",
+            "protocol": "ws",
+        }
+    },
+)
+asyncapi_doc.mount("/asyncapi.json")
+```
+
+生成的文档可以通过 `GET /asyncapi.json` 访问，也可以直接获取：
+
+```python
+document: dict = asyncapi_doc.generate()
+```
+
+## 装饰器语义
+
+输入和输出都支持单数或复数形式：
+
+```python
+@asyncapi(input=Request)
+@asyncapi(inputs=[RequestA, RequestB])
+@asyncapi(output=Response)
+@asyncapi(outputs=[Success, Failure])
+```
+
+支持以下组合：
+
+| 输入 | 输出 | AsyncAPI operation |
+| --- | --- | --- |
+| 一个或多个 | 无 | `action: receive`，不生成 `reply` |
+| 一个或多个 | 一个或多个 | `action: receive`，生成 `reply` |
+| 无 | 一个或多个 | `action: send`，表示服务器主动推送 |
+
+输入和输出同时为空的声明无效。`input` 和 `inputs` 不能同时使用，
+`output` 和 `outputs` 也不能同时使用。
+
+装饰器支持以下 operation 元数据：
+
+- `operation_id`：AsyncAPI `operations` map 中的显式 key。
+- `title`、`summary`、`description`：operation 文档信息。
+- `tags`：operation 分组标签。
+
+消息 payload schema 直接来自 Pydantic 模型的
+`model_json_schema()`。本项目只负责生成消息契约，不会解析、校验或转换
+运行时 WebSocket frame。
+
+## YAML 导出
+
+安装 `yaml` 可选依赖后：
+
+```python
+yaml_document = asyncapi_doc.to_yaml()
+```
+
+## 开发
+
+本项目使用 uv 管理依赖和构建：
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv build
+```
+
+## 相关链接
+
+- [AsyncAPI 3.0 规范](https://www.asyncapi.com/docs/reference/specification/v3.0.0)
+- [FastAPI WebSockets](https://fastapi.tiangolo.com/advanced/websockets/)
+- [Pydantic](https://docs.pydantic.dev/latest/)
+- [uv](https://docs.astral.sh/uv/)
+- [项目仓库](https://github.com/qingyiwebt/fast-asyncapidoc)
+
+## 许可证
+
+[MIT License](LICENSE)

fast_asyncapidoc-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "fast-asyncapidoc"
+version = "0.1.0"
+description = "Generate AsyncAPI 3 documentation for FastAPI WebSocket endpoints"
+readme = { file = "README.md", content-type = "text/markdown" }
+authors = [
+    { name = "qingyiwebt", email = "qingyiweb@gmail.com" },
+]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "asyncapi",
+    "documentation",
+    "fastapi",
+    "pydantic",
+    "websocket",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Documentation",
+    "Topic :: Internet",
+    "Topic :: Software Development :: Libraries",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.100,<1",
+    "pydantic>=2,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/qingyiwebt/fast-asyncapidoc"
+Repository = "https://github.com/qingyiwebt/fast-asyncapidoc"
+Documentation = "https://github.com/qingyiwebt/fast-asyncapidoc#readme"
+Issues = "https://github.com/qingyiwebt/fast-asyncapidoc/issues"
+
+[project.optional-dependencies]
+yaml = [
+    "pyyaml>=6",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.11,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+source-include = ["README.zh-CN.md"]
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+    "pytest>=9.2.0",
+    "ruff>=0.17.4",
+]

fast_asyncapidoc-0.1.0/src/fast_asyncapidoc/__init__.py

@@ -0,0 +1,20 @@
+"""Generate AsyncAPI 3 documentation for FastAPI WebSocket endpoints."""
+
+from .decorator import OperationSpec, asyncapi
+from .document import AsyncAPIDoc
+from .errors import (
+    AsyncAPIDocError,
+    DuplicateOperationIdError,
+    InvalidAsyncAPIDecoratorError,
+    MissingYamlDependencyError,
+)
+
+__all__ = [
+    "AsyncAPIDoc",
+    "AsyncAPIDocError",
+    "DuplicateOperationIdError",
+    "InvalidAsyncAPIDecoratorError",
+    "MissingYamlDependencyError",
+    "OperationSpec",
+    "asyncapi",
+]

fast_asyncapidoc-0.1.0/src/fast_asyncapidoc/decorator.py

@@ -0,0 +1,200 @@
+"""The endpoint decorator and its normalized metadata."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+from .errors import InvalidAsyncAPIDecoratorError
+
+EndpointT = TypeVar("EndpointT", bound=Callable[..., Any])
+ModelType = type[BaseModel]
+
+_SPECS_ATTRIBUTE = "__fast_asyncapidoc_specs__"
+
+
+@dataclass(frozen=True)
+class OperationSpec:
+    """One documented input/output interaction for a WebSocket endpoint."""
+
+    inputs: tuple[ModelType, ...]
+    outputs: tuple[ModelType, ...]
+    operation_id: str | None = None
+    title: str | None = None
+    summary: str | None = None
+    description: str | None = None
+    tags: tuple[str, ...] = ()
+
+
+def asyncapi(
+    *,
+    input: ModelType | None = None,
+    inputs: Sequence[ModelType] | None = None,
+    output: ModelType | None = None,
+    outputs: Sequence[ModelType] | None = None,
+    operation_id: str | None = None,
+    title: str | None = None,
+    summary: str | None = None,
+    description: str | None = None,
+    tags: Sequence[str] | None = None,
+) -> Callable[[EndpointT], EndpointT]:
+    """Attach an AsyncAPI interaction declaration to a WebSocket endpoint.
+
+    ``input`` and ``inputs`` are alternate spellings for a single or multiple
+    input models.  ``output`` and ``outputs`` behave the same way.  Either
+    side may be omitted for receive-only or server-push documentation, but
+    both sides may not be empty.  The decorator intentionally returns the
+    original callable instead of wrapping it, so FastAPI sees the original
+    signature and dependency metadata.
+    """
+
+    normalized_inputs = _normalize_models(
+        singular=input,
+        plural=inputs,
+        singular_name="input",
+        plural_name="inputs",
+        required=False,
+    )
+    normalized_outputs = _normalize_models(
+        singular=output,
+        plural=outputs,
+        singular_name="output",
+        plural_name="outputs",
+        required=False,
+    )
+
+    if not normalized_inputs and not normalized_outputs:
+        raise InvalidAsyncAPIDecoratorError(
+            "at least one input or output model is required"
+        )
+
+    normalized_operation_id = _normalize_optional_string(operation_id, "operation_id")
+    normalized_title = _normalize_optional_string(title, "title")
+    normalized_summary = _normalize_optional_string(summary, "summary")
+    normalized_description = _normalize_optional_string(description, "description")
+    normalized_tags = _normalize_tags(tags)
+
+    spec = OperationSpec(
+        inputs=normalized_inputs,
+        outputs=normalized_outputs,
+        operation_id=normalized_operation_id,
+        title=normalized_title,
+        summary=normalized_summary,
+        description=normalized_description,
+        tags=normalized_tags,
+    )
+
+    def decorate(endpoint: EndpointT) -> EndpointT:
+        if not callable(endpoint):
+            raise InvalidAsyncAPIDecoratorError(
+                "@asyncapi can only decorate a callable endpoint"
+            )
+
+        existing = list(getattr(endpoint, _SPECS_ATTRIBUTE, ()))
+        # Python applies stacked decorators from bottom to top.  Prepending
+        # makes generated documentation follow the order visible in source.
+        setattr(endpoint, _SPECS_ATTRIBUTE, (spec, *existing))
+        return endpoint
+
+    return decorate
+
+
+def get_operation_specs(endpoint: Any) -> tuple[OperationSpec, ...]:
+    """Return declarations attached to an endpoint, if any."""
+
+    candidates = [endpoint]
+    try:
+        unwrapped = inspect.unwrap(endpoint)
+    except (ValueError, TypeError):
+        unwrapped = None
+    if unwrapped is not None and unwrapped is not endpoint:
+        candidates.append(unwrapped)
+
+    for candidate in candidates:
+        specs = getattr(candidate, _SPECS_ATTRIBUTE, None)
+        if specs is not None:
+            return tuple(specs)
+    return ()
+
+
+def _normalize_models(
+    *,
+    singular: ModelType | None,
+    plural: Sequence[ModelType] | None,
+    singular_name: str,
+    plural_name: str,
+    required: bool,
+) -> tuple[ModelType, ...]:
+    if singular is not None and plural is not None:
+        raise InvalidAsyncAPIDecoratorError(
+            f"{singular_name!r} and {plural_name!r} are mutually exclusive"
+        )
+
+    if singular is not None:
+        values: tuple[Any, ...] = (singular,)
+    elif plural is not None:
+        if isinstance(plural, (str, bytes)):
+            raise InvalidAsyncAPIDecoratorError(
+                f"{plural_name!r} must be a sequence of Pydantic model classes"
+            )
+        try:
+            values = tuple(plural)
+        except TypeError as exc:
+            raise InvalidAsyncAPIDecoratorError(
+                f"{plural_name!r} must be a sequence of Pydantic model classes"
+            ) from exc
+    else:
+        values = ()
+
+    if required and not values:
+        raise InvalidAsyncAPIDecoratorError(
+            f"one of {singular_name!r} or {plural_name!r} is required"
+        )
+
+    normalized: list[ModelType] = []
+    seen: set[ModelType] = set()
+    for index, value in enumerate(values):
+        if not _is_model_type(value):
+            raise InvalidAsyncAPIDecoratorError(
+                f"{singular_name if singular is not None else plural_name}[{index}] "
+                "must be a Pydantic v2 BaseModel subclass"
+            )
+        if value not in seen:
+            seen.add(value)
+            normalized.append(value)
+    return tuple(normalized)
+
+
+def _is_model_type(value: Any) -> bool:
+    return isinstance(value, type) and issubclass(value, BaseModel)
+
+
+def _normalize_optional_string(value: str | None, name: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value.strip():
+        raise InvalidAsyncAPIDecoratorError(f"{name} must be a non-empty string")
+    return value
+
+
+def _normalize_tags(tags: Sequence[str] | None) -> tuple[str, ...]:
+    if tags is None:
+        return ()
+    if isinstance(tags, (str, bytes)):
+        raise InvalidAsyncAPIDecoratorError("tags must be a sequence of strings")
+    try:
+        values = tuple(tags)
+    except TypeError as exc:
+        raise InvalidAsyncAPIDecoratorError(
+            "tags must be a sequence of strings"
+        ) from exc
+    for index, tag in enumerate(values):
+        if not isinstance(tag, str) or not tag.strip():
+            raise InvalidAsyncAPIDecoratorError(
+                f"tags[{index}] must be a non-empty string"
+            )
+    return values

fast_asyncapidoc-0.1.0/src/fast_asyncapidoc/document.py

@@ -0,0 +1,349 @@
+"""AsyncAPI 3 document generation and optional FastAPI mounting."""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import re
+from collections.abc import Mapping
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+
+from .decorator import OperationSpec, get_operation_specs
+from .errors import DuplicateOperationIdError, MissingYamlDependencyError
+from .scanner import WebSocketRouteInfo, iter_websocket_routes
+
+_ASYNCAPI_VERSION = "3.0.0"
+_JSON_CONTENT_TYPE = "application/json"
+_WEBSOCKET_BINDING_VERSION = "0.1.0"
+_KEY_PATTERN = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+class AsyncAPIDoc:
+    """Generate AsyncAPI 3 documentation from a FastAPI application."""
+
+    def __init__(
+        self,
+        app: FastAPI,
+        *,
+        title: str,
+        version: str,
+        description: str | None = None,
+        servers: Mapping[str, Mapping[str, Any]] | None = None,
+    ) -> None:
+        if not hasattr(app, "routes") or not hasattr(app, "add_api_route"):
+            raise TypeError("app must be a FastAPI application")
+        if not isinstance(title, str) or not title.strip():
+            raise ValueError("title must be a non-empty string")
+        if not isinstance(version, str) or not version.strip():
+            raise ValueError("version must be a non-empty string")
+        if description is not None and not isinstance(description, str):
+            raise TypeError("description must be a string or None")
+
+        self.app = app
+        self.title = title
+        self.version = version
+        self.description = description
+        self.servers = copy.deepcopy(dict(servers)) if servers is not None else None
+        self._mounted_paths: set[str] = set()
+
+    def generate(self) -> dict[str, Any]:
+        """Build and return a fresh AsyncAPI document dictionary."""
+
+        document: dict[str, Any] = {
+            "asyncapi": _ASYNCAPI_VERSION,
+            "info": {
+                "title": self.title,
+                "version": self.version,
+            },
+            "defaultContentType": _JSON_CONTENT_TYPE,
+            "channels": {},
+            "operations": {},
+            "components": {
+                "schemas": {},
+                "messages": {},
+            },
+        }
+        if self.description is not None:
+            document["info"]["description"] = self.description
+        if self.servers is not None:
+            document["servers"] = copy.deepcopy(self.servers)
+
+        context = _GenerationContext(document)
+        for route in iter_websocket_routes(self.app.routes):
+            context.add_route(route)
+        return document
+
+    def mount(self, path: str = "/asyncapi.json", *, name: str = "asyncapi") -> None:
+        """Mount a JSON document endpoint on the FastAPI application."""
+
+        if not isinstance(path, str) or not path.startswith("/"):
+            raise ValueError("path must be an absolute route path")
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError("name must be a non-empty string")
+        if path in self._mounted_paths:
+            return
+
+        async def asyncapi_json() -> dict[str, Any]:
+            return self.generate()
+
+        self.app.add_api_route(
+            path,
+            asyncapi_json,
+            methods=["GET"],
+            name=name,
+            include_in_schema=False,
+            response_class=JSONResponse,
+        )
+        self._mounted_paths.add(path)
+
+    def to_yaml(self, *, sort_keys: bool = False) -> str:
+        """Serialize the generated document as YAML using the optional extra."""
+
+        try:
+            import yaml
+        except ImportError as exc:  # pragma: no cover - depends on installation
+            raise MissingYamlDependencyError(
+                "YAML support requires the optional dependency; install "
+                "fast-asyncapidoc[yaml]"
+            ) from exc
+
+        return yaml.safe_dump(
+            self.generate(),
+            allow_unicode=True,
+            sort_keys=sort_keys,
+        )
+
+
+class _GenerationContext:
+    def __init__(self, document: dict[str, Any]) -> None:
+        self.document = document
+        self.channels: dict[str, Any] = document["channels"]
+        self.operations: dict[str, Any] = document["operations"]
+        self.schemas: dict[str, Any] = document["components"]["schemas"]
+        self.messages: dict[str, Any] = document["components"]["messages"]
+        self.schema_keys_by_model: dict[type[Any], str] = {}
+        self.message_keys: dict[tuple[str, str, str], str] = {}
+
+    def add_route(self, route: WebSocketRouteInfo) -> None:
+        specs = get_operation_specs(route.endpoint)
+        if not specs:
+            return
+
+        channel_id = self._channel_id(route.path)
+        channel = self.channels.setdefault(
+            channel_id,
+            {
+                "address": route.path,
+                "bindings": {"ws": {"bindingVersion": _WEBSOCKET_BINDING_VERSION}},
+                "messages": {},
+            },
+        )
+        if channel["address"] != route.path:
+            channel_id = self._unique_key(channel_id, route.path, self.channels)
+            channel = self.channels.setdefault(
+                channel_id,
+                {
+                    "address": route.path,
+                    "bindings": {"ws": {"bindingVersion": _WEBSOCKET_BINDING_VERSION}},
+                    "messages": {},
+                },
+            )
+
+        for index, spec in enumerate(specs):
+            operation_id = self._operation_id(route, spec, index)
+            has_inputs = bool(spec.inputs)
+            has_outputs = bool(spec.outputs)
+            operation: dict[str, Any] = {
+                "action": "receive" if has_inputs else "send",
+                "channel": {"$ref": f"#/channels/{channel_id}"},
+                "messages": [],
+            }
+            self._add_operation_metadata(operation, spec)
+
+            if has_inputs:
+                input_refs = [
+                    self._register_message(
+                        channel=channel,
+                        channel_id=channel_id,
+                        direction="input",
+                        model=model,
+                    )
+                    for model in spec.inputs
+                ]
+                operation["messages"] = self._message_refs(channel_id, input_refs)
+
+            if has_inputs and has_outputs:
+                output_ids = [
+                    self._register_message(
+                        channel=channel,
+                        channel_id=channel_id,
+                        direction="output",
+                        model=model,
+                    )
+                    for model in spec.outputs
+                ]
+                operation["reply"] = {
+                    "channel": {"$ref": f"#/channels/{channel_id}"},
+                    "messages": self._message_refs(channel_id, output_ids),
+                }
+            elif has_outputs:
+                output_ids = [
+                    self._register_message(
+                        channel=channel,
+                        channel_id=channel_id,
+                        direction="output",
+                        model=model,
+                    )
+                    for model in spec.outputs
+                ]
+                operation["messages"] = self._message_refs(channel_id, output_ids)
+
+            self.operations[operation_id] = operation
+
+    @staticmethod
+    def _message_refs(channel_id: str, message_ids: list[str]) -> list[dict[str, str]]:
+        return [
+            {"$ref": f"#/channels/{channel_id}/messages/{message_id}"}
+            for message_id in message_ids
+        ]
+
+    def _operation_id(
+        self, route: WebSocketRouteInfo, spec: OperationSpec, index: int
+    ) -> str:
+        if spec.operation_id is not None:
+            if spec.operation_id in self.operations:
+                raise DuplicateOperationIdError(
+                    f"duplicate operation_id: {spec.operation_id!r}"
+                )
+            return spec.operation_id
+
+        endpoint_name = getattr(route.endpoint, "__name__", None)
+        base = route.name or endpoint_name or "websocket"
+        if len(get_operation_specs(route.endpoint)) > 1:
+            base = f"{base}__{index + 1}"
+        return self._unique_key(base, f"{route.path}:{index}", self.operations)
+
+    def _add_operation_metadata(
+        self, operation: dict[str, Any], spec: OperationSpec
+    ) -> None:
+        if spec.title is not None:
+            operation["title"] = spec.title
+        if spec.summary is not None:
+            operation["summary"] = spec.summary
+        if spec.description is not None:
+            operation["description"] = spec.description
+        if spec.tags:
+            operation["tags"] = [{"name": tag} for tag in spec.tags]
+
+    def _register_message(
+        self,
+        *,
+        channel: dict[str, Any],
+        channel_id: str,
+        direction: str,
+        model: type[Any],
+    ) -> str:
+        schema_key = self._register_model_schema(model)
+        message_key = (channel_id, direction, schema_key)
+        message_id = self.message_keys.get(message_key)
+        if message_id is None:
+            base_message_id = _safe_key(f"{channel_id}_{direction}_{schema_key}")
+            message_id = self._unique_key(
+                base_message_id,
+                f"{channel_id}:{direction}:{schema_key}",
+                self.messages,
+            )
+            self.message_keys[message_key] = message_id
+
+        if message_id not in self.messages:
+            schema = self.schemas[schema_key]
+            message: dict[str, Any] = {
+                "name": message_id,
+                "contentType": _JSON_CONTENT_TYPE,
+                "payload": {"$ref": f"#/components/schemas/{schema_key}"},
+            }
+            if isinstance(schema.get("title"), str):
+                message["title"] = schema["title"]
+            if isinstance(schema.get("description"), str):
+                message["description"] = schema["description"]
+            self.messages[message_id] = message
+
+        channel["messages"][message_id] = {
+            "$ref": f"#/components/messages/{message_id}"
+        }
+        return message_id
+
+    def _register_model_schema(self, model: type[Any]) -> str:
+        existing_key = self.schema_keys_by_model.get(model)
+        if existing_key is not None:
+            return existing_key
+
+        raw_schema = copy.deepcopy(
+            model.model_json_schema(ref_template="#/components/schemas/{model}")
+        )
+        definitions = raw_schema.pop("$defs", {})
+        local_keys: dict[str, str] = {}
+        for name, schema in definitions.items():
+            local_keys[name] = self._schema_key(name, schema)
+        root_key = self._schema_key(model.__name__, raw_schema)
+        self.schema_keys_by_model[model] = root_key
+
+        for name, schema in definitions.items():
+            key = local_keys[name]
+            rewritten = _rewrite_schema_refs(schema, local_keys)
+            if key not in self.schemas:
+                self.schemas[key] = rewritten
+        self.schemas[root_key] = _rewrite_schema_refs(raw_schema, local_keys)
+        return root_key
+
+    def _schema_key(self, name: str, schema: Any) -> str:
+        base = _safe_key(name) or "Model"
+        return self._unique_key(base, json.dumps(schema, sort_keys=True), self.schemas)
+
+    @staticmethod
+    def _channel_id(path: str) -> str:
+        stripped = path.strip("/")
+        if not stripped:
+            return "root"
+        return _safe_key(stripped.replace("/", "_")) or "channel"
+
+    @staticmethod
+    def _unique_key(base: str, identity: str, existing: Mapping[str, Any]) -> str:
+        if base not in existing:
+            return base
+        if identity == base:
+            return base
+        digest = hashlib.sha1(identity.encode("utf-8")).hexdigest()[:8]
+        candidate = f"{base}__{digest}"
+        counter = 2
+        while candidate in existing:
+            candidate = f"{base}__{digest}_{counter}"
+            counter += 1
+        return candidate
+
+
+def _safe_key(value: str) -> str:
+    value = _KEY_PATTERN.sub("_", value).strip("._-")
+    return value or "item"
+
+
+def _rewrite_schema_refs(value: Any, local_keys: Mapping[str, str]) -> Any:
+    if isinstance(value, dict):
+        rewritten: dict[str, Any] = {}
+        for key, child in value.items():
+            if key == "$ref" and isinstance(child, str):
+                if child.startswith("#/$defs/"):
+                    name = child.removeprefix("#/$defs/")
+                    child = f"#/components/schemas/{local_keys.get(name, name)}"
+                elif child.startswith("#/components/schemas/"):
+                    name = child.removeprefix("#/components/schemas/")
+                    child = f"#/components/schemas/{local_keys.get(name, name)}"
+            rewritten[key] = _rewrite_schema_refs(child, local_keys)
+        return rewritten
+    if isinstance(value, list):
+        return [_rewrite_schema_refs(item, local_keys) for item in value]
+    return value

fast_asyncapidoc-0.1.0/src/fast_asyncapidoc/errors.py

@@ -0,0 +1,17 @@
+"""Public exceptions raised by :mod:`fast_asyncapidoc`."""
+
+
+class AsyncAPIDocError(Exception):
+    """Base exception for fast-asyncapidoc errors."""
+
+
+class InvalidAsyncAPIDecoratorError(AsyncAPIDocError, ValueError):
+    """Raised when an ``@asyncapi`` declaration is invalid."""
+
+
+class DuplicateOperationIdError(AsyncAPIDocError, ValueError):
+    """Raised when two operations use the same explicit operation ID."""
+
+
+class MissingYamlDependencyError(AsyncAPIDocError, RuntimeError):
+    """Raised when YAML serialization is requested without PyYAML installed."""

fast_asyncapidoc-0.1.0/src/fast_asyncapidoc/scanner.py

@@ -0,0 +1,104 @@
+"""FastAPI/Starlette WebSocket route discovery."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi.routing import APIWebSocketRoute
+from starlette.routing import Mount, WebSocketRoute
+
+
+@dataclass(frozen=True)
+class WebSocketRouteInfo:
+    """The route information needed by the document generator."""
+
+    path: str
+    endpoint: Any
+    name: str | None
+
+
+_WEBSOCKET_ROUTE_TYPES = (APIWebSocketRoute, WebSocketRoute)
+
+
+def iter_websocket_routes(routes: Iterable[Any]) -> Iterator[WebSocketRouteInfo]:
+    """Yield WebSocket routes with their effective mounted paths.
+
+    FastAPI releases that use lazy router inclusion expose an internal
+    ``_IncludedRouter`` object rather than flattening routes into
+    ``app.routes``.  Its capability-based ``effective_route_contexts`` method
+    gives us the final Starlette route and therefore preserves include
+    prefixes.  Older FastAPI releases continue to work through the direct
+    route and Mount branches below.
+    """
+
+    for route in routes:
+        if isinstance(route, _WEBSOCKET_ROUTE_TYPES):
+            yield _route_info(route)
+            continue
+
+        effective_contexts = getattr(route, "effective_route_contexts", None)
+        if callable(effective_contexts):
+            for context in effective_contexts():
+                effective_route = getattr(context, "starlette_route", None)
+                original_route = getattr(context, "original_route", None)
+                if isinstance(effective_route, _WEBSOCKET_ROUTE_TYPES):
+                    yield _route_info(
+                        effective_route,
+                        endpoint=getattr(original_route, "endpoint", None),
+                    )
+                else:
+                    nested_routes = getattr(effective_route, "routes", None)
+                    if nested_routes is not None:
+                        yield from iter_websocket_routes(nested_routes)
+            continue
+
+        if isinstance(route, Mount):
+            nested_routes = getattr(route, "routes", None)
+            if nested_routes is not None:
+                prefix = getattr(route, "path", "")
+                yield from _with_prefix(iter_websocket_routes(nested_routes), prefix)
+            continue
+
+        nested_routes = getattr(route, "routes", None)
+        if nested_routes is not None:
+            yield from iter_websocket_routes(nested_routes)
+
+
+def _route_info(route: Any, *, endpoint: Any | None = None) -> WebSocketRouteInfo:
+    actual_endpoint = (
+        endpoint if endpoint is not None else getattr(route, "endpoint", None)
+    )
+    return WebSocketRouteInfo(
+        path=getattr(route, "path", "/") or "/",
+        endpoint=actual_endpoint,
+        name=getattr(route, "name", None),
+    )
+
+
+def _with_prefix(
+    routes: Iterable[WebSocketRouteInfo], prefix: str
+) -> Iterator[WebSocketRouteInfo]:
+    for route in routes:
+        yield WebSocketRouteInfo(
+            path=join_paths(prefix, route.path),
+            endpoint=route.endpoint,
+            name=route.name,
+        )
+
+
+def join_paths(prefix: str, path: str) -> str:
+    """Join mounted paths while preserving a route's trailing slash."""
+
+    prefix = prefix or ""
+    path = path or "/"
+    if not prefix or prefix == "/":
+        return path if path.startswith("/") else f"/{path}"
+    if path == "/":
+        return prefix if prefix.startswith("/") else f"/{prefix}"
+
+    result = f"/{prefix.strip('/')}/{path.strip('/')}"
+    if path.endswith("/") and not result.endswith("/"):
+        result += "/"
+    return result