rechain
5 months ago
9 changed files with 502 additions and 233 deletions
@ -0,0 +1,2 @@ |
|||||
|
ASYNCAPI_VERSION = "2.6.0" |
||||
|
REF_PREFIX = "#/components/schemas/" |
||||
@ -0,0 +1,127 @@ |
|||||
|
from typing import Annotated |
||||
|
|
||||
|
from annotated_doc import Doc |
||||
|
from starlette.responses import HTMLResponse |
||||
|
|
||||
|
|
||||
|
def get_asyncapi_html( |
||||
|
*, |
||||
|
asyncapi_url: Annotated[ |
||||
|
str, |
||||
|
Doc( |
||||
|
""" |
||||
|
The AsyncAPI URL that AsyncAPI Studio should load and use. |
||||
|
|
||||
|
This is normally done automatically by FastAPI using the default URL |
||||
|
`/asyncapi.json`. |
||||
|
|
||||
|
Read more about it in the |
||||
|
[FastAPI docs for AsyncAPI](https://fastapi.tiangolo.com/advanced/asyncapi/). |
||||
|
""" |
||||
|
), |
||||
|
], |
||||
|
title: Annotated[ |
||||
|
str, |
||||
|
Doc( |
||||
|
""" |
||||
|
The HTML `<title>` content, normally shown in the browser tab. |
||||
|
""" |
||||
|
), |
||||
|
], |
||||
|
asyncapi_js_url: Annotated[ |
||||
|
str, |
||||
|
Doc( |
||||
|
""" |
||||
|
The URL to use to load the AsyncAPI Studio JavaScript. |
||||
|
|
||||
|
It is normally set to a CDN URL. |
||||
|
""" |
||||
|
), |
||||
|
] = "https://unpkg.com/@asyncapi/react-component@latest/browser/standalone/index.js", |
||||
|
asyncapi_favicon_url: Annotated[ |
||||
|
str, |
||||
|
Doc( |
||||
|
""" |
||||
|
The URL of the favicon to use. It is normally shown in the browser tab. |
||||
|
""" |
||||
|
), |
||||
|
] = "https://fastapi.tiangolo.com/img/favicon.png", |
||||
|
docs_url: Annotated[ |
||||
|
str | None, |
||||
|
Doc( |
||||
|
""" |
||||
|
The URL to the OpenAPI docs (Swagger UI) for navigation link. |
||||
|
""" |
||||
|
), |
||||
|
] = None, |
||||
|
) -> HTMLResponse: |
||||
|
""" |
||||
|
Generate and return the HTML that loads AsyncAPI Studio for the interactive |
||||
|
WebSocket API docs (normally served at `/asyncapi-docs`). |
||||
|
|
||||
|
You would only call this function yourself if you needed to override some parts, |
||||
|
for example the URLs to use to load AsyncAPI Studio's JavaScript. |
||||
|
""" |
||||
|
navigation_html = "" |
||||
|
if docs_url: |
||||
|
navigation_html = f""" |
||||
|
<div style="padding: 10px; background-color: #f5f5f5; border-bottom: 1px solid #ddd;"> |
||||
|
<a href="{docs_url}" style="color: #007bff; text-decoration: none; margin-right: 20px;"> |
||||
|
📄 OpenAPI Docs (REST API) |
||||
|
</a> |
||||
|
<span style="color: #666;">WebSocket API Documentation</span> |
||||
|
</div> |
||||
|
""" |
||||
|
|
||||
|
html = f""" |
||||
|
<!DOCTYPE html> |
||||
|
<html> |
||||
|
<head> |
||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
||||
|
<link rel="shortcut icon" href="{asyncapi_favicon_url}"> |
||||
|
<title>{title}</title> |
||||
|
<style> |
||||
|
body {{ |
||||
|
margin: 0; |
||||
|
padding: 0; |
||||
|
}} |
||||
|
#asyncapi {{ |
||||
|
height: 100vh; |
||||
|
width: 100%; |
||||
|
}} |
||||
|
</style> |
||||
|
</head> |
||||
|
<body> |
||||
|
{navigation_html} |
||||
|
<div id="asyncapi"></div> |
||||
|
<script src="{asyncapi_js_url}"></script> |
||||
|
<script> |
||||
|
(async function() {{ |
||||
|
const asyncapiSpec = await fetch('{asyncapi_url}').then(res => res.json()); |
||||
|
const AsyncApiStandalone = window.AsyncApiStandalone || window.AsyncAPIStandalone; |
||||
|
if (AsyncApiStandalone) {{ |
||||
|
AsyncApiStandalone.render({{ |
||||
|
schema: asyncapiSpec, |
||||
|
config: {{ |
||||
|
show: {{ |
||||
|
sidebar: true, |
||||
|
info: true, |
||||
|
servers: true, |
||||
|
operations: true, |
||||
|
messages: true, |
||||
|
}}, |
||||
|
}}, |
||||
|
}}, document.getElementById('asyncapi')); |
||||
|
}} else {{ |
||||
|
document.getElementById('asyncapi').innerHTML = |
||||
|
'<div style="padding: 20px; text-align: center;">' + |
||||
|
'<h2>Failed to load AsyncAPI Studio</h2>' + |
||||
|
'<p>Please check your internet connection and try again.</p>' + |
||||
|
'</div>'; |
||||
|
}} |
||||
|
}})(); |
||||
|
</script> |
||||
|
</body> |
||||
|
</html> |
||||
|
""" |
||||
|
return HTMLResponse(html) |
||||
@ -0,0 +1,224 @@ |
|||||
|
from collections.abc import Sequence |
||||
|
from typing import Any |
||||
|
|
||||
|
from pydantic import BaseModel |
||||
|
|
||||
|
from fastapi import routing |
||||
|
from fastapi.asyncapi.constants import ASYNCAPI_VERSION, REF_PREFIX |
||||
|
from fastapi.encoders import jsonable_encoder |
||||
|
from starlette.routing import BaseRoute |
||||
|
|
||||
|
|
||||
|
def get_asyncapi_channel( |
||||
|
*, |
||||
|
route: routing.APIWebSocketRoute, |
||||
|
subscribe_payload_schema: dict[str, Any] | None = None, |
||||
|
publish_payload_schema: dict[str, Any] | None = None, |
||||
|
) -> dict[str, Any]: |
||||
|
"""Generate AsyncAPI channel definition for a WebSocket route.""" |
||||
|
channel: dict[str, Any] = {} |
||||
|
|
||||
|
# WebSocket channels typically have subscribe operation |
||||
|
# (client subscribes to receive messages from server) |
||||
|
operation: dict[str, Any] = { |
||||
|
"operationId": route.name or f"websocket_{route.path_format}", |
||||
|
} |
||||
|
|
||||
|
# Message schema: contentType and optional payload (schema for message body) |
||||
|
subscribe_message: dict[str, Any] = { |
||||
|
"contentType": "application/json", |
||||
|
} |
||||
|
if subscribe_payload_schema: |
||||
|
subscribe_message["payload"] = subscribe_payload_schema |
||||
|
|
||||
|
operation["message"] = subscribe_message |
||||
|
channel["subscribe"] = operation |
||||
|
|
||||
|
# WebSockets are bidirectional, so we also include publish |
||||
|
# (client can publish messages to server) |
||||
|
publish_operation: dict[str, Any] = { |
||||
|
"operationId": f"{route.name or f'websocket_{route.path_format}'}_publish", |
||||
|
"message": { |
||||
|
"contentType": "application/json", |
||||
|
**({"payload": publish_payload_schema} if publish_payload_schema else {}), |
||||
|
}, |
||||
|
} |
||||
|
channel["publish"] = publish_operation |
||||
|
|
||||
|
return channel |
||||
|
|
||||
|
|
||||
|
def _get_fields_from_websocket_routes( |
||||
|
routes: Sequence[BaseRoute], |
||||
|
) -> list[Any]: |
||||
|
"""Collect body (ModelField) params from WebSocket routes for schema generation.""" |
||||
|
from fastapi.dependencies.utils import get_flat_dependant |
||||
|
|
||||
|
from fastapi._compat import ModelField |
||||
|
from pydantic.fields import FieldInfo |
||||
|
|
||||
|
fields: list[Any] = [] |
||||
|
seen_models: set[type[BaseModel]] = set() |
||||
|
for route in routes or []: |
||||
|
if not isinstance(route, routing.APIWebSocketRoute): |
||||
|
continue |
||||
|
flat_dependant = get_flat_dependant(route.dependant, skip_repeats=True) |
||||
|
fields.extend(flat_dependant.body_params) |
||||
|
# Add explicit subscribe_schema / publish_schema as ModelFields so they get definitions |
||||
|
for model in ( |
||||
|
getattr(route, "subscribe_schema", None), |
||||
|
getattr(route, "publish_schema", None), |
||||
|
): |
||||
|
if model is not None and isinstance(model, type) and issubclass(model, BaseModel) and model not in seen_models: |
||||
|
seen_models.add(model) |
||||
|
fields.append( |
||||
|
ModelField( |
||||
|
field_info=FieldInfo(annotation=model), |
||||
|
name=model.__name__, |
||||
|
mode="validation", |
||||
|
) |
||||
|
) |
||||
|
return fields |
||||
|
|
||||
|
|
||||
|
def get_asyncapi( |
||||
|
*, |
||||
|
title: str, |
||||
|
version: str, |
||||
|
asyncapi_version: str = ASYNCAPI_VERSION, |
||||
|
summary: str | None = None, |
||||
|
description: str | None = None, |
||||
|
routes: Sequence[BaseRoute], |
||||
|
servers: list[dict[str, str | Any]] | None = None, |
||||
|
terms_of_service: str | None = None, |
||||
|
contact: dict[str, str | Any] | None = None, |
||||
|
license_info: dict[str, str | Any] | None = None, |
||||
|
external_docs: dict[str, Any] | None = None, |
||||
|
) -> dict[str, Any]: |
||||
|
""" |
||||
|
Generate AsyncAPI schema from FastAPI application routes. |
||||
|
|
||||
|
Filters for WebSocket routes and generates AsyncAPI 2.6.0 compliant schema. |
||||
|
Includes components/schemas for message payloads when WebSocket routes use |
||||
|
Pydantic models (e.g. via Body() in dependencies). |
||||
|
""" |
||||
|
from fastapi._compat import ( |
||||
|
ModelField, |
||||
|
get_definitions, |
||||
|
get_flat_models_from_fields, |
||||
|
get_model_name_map, |
||||
|
get_schema_from_model_field, |
||||
|
) |
||||
|
|
||||
|
info: dict[str, Any] = {"title": title, "version": version} |
||||
|
if summary: |
||||
|
info["summary"] = summary |
||||
|
if description: |
||||
|
info["description"] = description |
||||
|
if terms_of_service: |
||||
|
info["termsOfService"] = terms_of_service |
||||
|
if contact: |
||||
|
info["contact"] = contact |
||||
|
if license_info: |
||||
|
info["license"] = license_info |
||||
|
|
||||
|
output: dict[str, Any] = {"asyncapi": asyncapi_version, "info": info} |
||||
|
|
||||
|
# Add default WebSocket server if no servers provided and we have WebSocket routes |
||||
|
websocket_routes = [ |
||||
|
route for route in routes or [] if isinstance(route, routing.APIWebSocketRoute) |
||||
|
] |
||||
|
if websocket_routes and not servers: |
||||
|
# Default WebSocket server - can be overridden by providing servers parameter |
||||
|
output["servers"] = [ |
||||
|
{ |
||||
|
"url": "ws://localhost:8000", |
||||
|
"protocol": "ws", |
||||
|
"description": "WebSocket server", |
||||
|
} |
||||
|
] |
||||
|
elif servers: |
||||
|
output["servers"] = servers |
||||
|
|
||||
|
# Build components/schemas from WebSocket body params and explicit subscribe/publish_schema |
||||
|
ws_fields = _get_fields_from_websocket_routes(routes or []) |
||||
|
components: dict[str, Any] = {} |
||||
|
route_subscribe_schemas: dict[str, dict[str, Any] | None] = {} |
||||
|
route_publish_schemas: dict[str, dict[str, Any] | None] = {} |
||||
|
if ws_fields: |
||||
|
flat_models = get_flat_models_from_fields(ws_fields, known_models=set()) |
||||
|
model_name_map = get_model_name_map(flat_models) |
||||
|
field_mapping, definitions = get_definitions( |
||||
|
fields=ws_fields, |
||||
|
model_name_map=model_name_map, |
||||
|
separate_input_output_schemas=True, |
||||
|
) |
||||
|
if definitions: |
||||
|
components["schemas"] = {k: definitions[k] for k in sorted(definitions)} |
||||
|
# For each WebSocket route, resolve subscribe and publish payload schemas |
||||
|
for route in routes or []: |
||||
|
if not isinstance(route, routing.APIWebSocketRoute): |
||||
|
continue |
||||
|
sub_schema: dict[str, Any] | None = None |
||||
|
pub_schema: dict[str, Any] | None = None |
||||
|
# Explicit subscribe_schema / publish_schema (e.g. when route has no Body() in Depends) |
||||
|
subscribe_model = getattr(route, "subscribe_schema", None) |
||||
|
publish_model = getattr(route, "publish_schema", None) |
||||
|
if subscribe_model is not None and isinstance(subscribe_model, type) and issubclass(subscribe_model, BaseModel): |
||||
|
sub_schema = {"$ref": f"{REF_PREFIX}{subscribe_model.__name__}"} |
||||
|
if publish_model is not None and isinstance(publish_model, type) and issubclass(publish_model, BaseModel): |
||||
|
pub_schema = {"$ref": f"{REF_PREFIX}{publish_model.__name__}"} |
||||
|
# Fall back to first body param (Depends with Body()) for both if not set |
||||
|
if sub_schema is None or pub_schema is None: |
||||
|
flat_dependant = route._flat_dependant |
||||
|
if flat_dependant.body_params: |
||||
|
first_body = flat_dependant.body_params[0] |
||||
|
if isinstance(first_body, ModelField): |
||||
|
body_schema = get_schema_from_model_field( |
||||
|
field=first_body, |
||||
|
model_name_map=model_name_map, |
||||
|
field_mapping=field_mapping, |
||||
|
separate_input_output_schemas=True, |
||||
|
) |
||||
|
# Use only $ref for channel payload when schema is in components |
||||
|
if "$ref" in body_schema and body_schema["$ref"].startswith( |
||||
|
REF_PREFIX |
||||
|
): |
||||
|
body_schema = {"$ref": body_schema["$ref"]} |
||||
|
if sub_schema is None: |
||||
|
sub_schema = body_schema |
||||
|
if pub_schema is None: |
||||
|
pub_schema = body_schema |
||||
|
route_subscribe_schemas[route.path_format] = sub_schema |
||||
|
route_publish_schemas[route.path_format] = pub_schema |
||||
|
else: |
||||
|
for route in routes or []: |
||||
|
if not isinstance(route, routing.APIWebSocketRoute): |
||||
|
continue |
||||
|
route_subscribe_schemas[route.path_format] = None |
||||
|
route_publish_schemas[route.path_format] = None |
||||
|
|
||||
|
channels: dict[str, dict[str, Any]] = {} |
||||
|
|
||||
|
# Filter routes to only include WebSocket routes |
||||
|
for route in routes or []: |
||||
|
if isinstance(route, routing.APIWebSocketRoute): |
||||
|
sub_schema = route_subscribe_schemas.get(route.path_format) |
||||
|
pub_schema = route_publish_schemas.get(route.path_format) |
||||
|
channel = get_asyncapi_channel( |
||||
|
route=route, |
||||
|
subscribe_payload_schema=sub_schema, |
||||
|
publish_payload_schema=pub_schema, |
||||
|
) |
||||
|
if channel: |
||||
|
channels[route.path_format] = channel |
||||
|
|
||||
|
output["channels"] = channels |
||||
|
|
||||
|
if components: |
||||
|
output["components"] = components |
||||
|
|
||||
|
if external_docs: |
||||
|
output["externalDocs"] = external_docs |
||||
|
|
||||
|
return jsonable_encoder(output, by_alias=True, exclude_none=True) # type: ignore |
||||
@ -1,105 +0,0 @@ |
|||||
from collections.abc import Sequence |
|
||||
from typing import Any |
|
||||
|
|
||||
from fastapi import routing |
|
||||
from fastapi.encoders import jsonable_encoder |
|
||||
from starlette.routing import BaseRoute |
|
||||
|
|
||||
|
|
||||
def get_asyncapi_channel( |
|
||||
*, |
|
||||
route: routing.APIWebSocketRoute, |
|
||||
) -> dict[str, Any]: |
|
||||
"""Generate AsyncAPI channel definition for a WebSocket route.""" |
|
||||
channel: dict[str, Any] = {} |
|
||||
|
|
||||
# WebSocket channels typically have subscribe operation |
|
||||
# (client subscribes to receive messages from server) |
|
||||
operation: dict[str, Any] = { |
|
||||
"operationId": route.name or f"websocket_{route.path_format}", |
|
||||
} |
|
||||
|
|
||||
# Basic message schema - can be enhanced later with actual message types |
|
||||
# For WebSockets, messages can be sent in both directions |
|
||||
message: dict[str, Any] = { |
|
||||
"contentType": "application/json", |
|
||||
} |
|
||||
|
|
||||
operation["message"] = message |
|
||||
channel["subscribe"] = operation |
|
||||
|
|
||||
# WebSockets are bidirectional, so we also include publish |
|
||||
# (client can publish messages to server) |
|
||||
publish_operation: dict[str, Any] = { |
|
||||
"operationId": f"{route.name or f'websocket_{route.path_format}'}_publish", |
|
||||
"message": message, |
|
||||
} |
|
||||
channel["publish"] = publish_operation |
|
||||
|
|
||||
return channel |
|
||||
|
|
||||
|
|
||||
def get_asyncapi( |
|
||||
*, |
|
||||
title: str, |
|
||||
version: str, |
|
||||
asyncapi_version: str = "2.6.0", |
|
||||
summary: str | None = None, |
|
||||
description: str | None = None, |
|
||||
routes: Sequence[BaseRoute], |
|
||||
servers: list[dict[str, str | Any]] | None = None, |
|
||||
terms_of_service: str | None = None, |
|
||||
contact: dict[str, str | Any] | None = None, |
|
||||
license_info: dict[str, str | Any] | None = None, |
|
||||
external_docs: dict[str, Any] | None = None, |
|
||||
) -> dict[str, Any]: |
|
||||
""" |
|
||||
Generate AsyncAPI schema from FastAPI application routes. |
|
||||
|
|
||||
Filters for WebSocket routes and generates AsyncAPI 2.6.0 compliant schema. |
|
||||
""" |
|
||||
info: dict[str, Any] = {"title": title, "version": version} |
|
||||
if summary: |
|
||||
info["summary"] = summary |
|
||||
if description: |
|
||||
info["description"] = description |
|
||||
if terms_of_service: |
|
||||
info["termsOfService"] = terms_of_service |
|
||||
if contact: |
|
||||
info["contact"] = contact |
|
||||
if license_info: |
|
||||
info["license"] = license_info |
|
||||
|
|
||||
output: dict[str, Any] = {"asyncapi": asyncapi_version, "info": info} |
|
||||
|
|
||||
# Add default WebSocket server if no servers provided and we have WebSocket routes |
|
||||
websocket_routes = [ |
|
||||
route for route in routes or [] if isinstance(route, routing.APIWebSocketRoute) |
|
||||
] |
|
||||
if websocket_routes and not servers: |
|
||||
# Default WebSocket server - can be overridden by providing servers parameter |
|
||||
output["servers"] = [ |
|
||||
{ |
|
||||
"url": "ws://localhost:8000", |
|
||||
"protocol": "ws", |
|
||||
"description": "WebSocket server", |
|
||||
} |
|
||||
] |
|
||||
elif servers: |
|
||||
output["servers"] = servers |
|
||||
|
|
||||
channels: dict[str, dict[str, Any]] = {} |
|
||||
|
|
||||
# Filter routes to only include WebSocket routes |
|
||||
for route in routes or []: |
|
||||
if isinstance(route, routing.APIWebSocketRoute): |
|
||||
channel = get_asyncapi_channel(route=route) |
|
||||
if channel: |
|
||||
channels[route.path_format] = channel |
|
||||
|
|
||||
output["channels"] = channels |
|
||||
|
|
||||
if external_docs: |
|
||||
output["externalDocs"] = external_docs |
|
||||
|
|
||||
return jsonable_encoder(output, by_alias=True, exclude_none=True) # type: ignore |
|
||||
Loading…
Reference in new issue