Merge pull request #118 from touale/opt-api-router-tags

Opt api router tags

Author: touale

src/framex/consts.py

@@ -19,3 +19,5 @@
     "/health",
     "/ping",
 ]
+
+AUTH_COOKIE_NAME = "framex_token"

src/framex/driver/application.py

@@ -95,6 +95,8 @@ async def _on_start(deployment: Any) -> None:
         redirect_slashes=False,
     )
 
+    application.state.tags_metadata_map = []
+
     if settings.auth.oauth:
         application.add_api_route(
             settings.auth.oauth.redirect_uri,
@@ -118,6 +120,7 @@ async def get_open_api_endpoint(_: Annotated[str, Depends(authenticate)]) -> dic
             version=VERSION,
             description=build_openapi_description(),
             routes=application.routes,
+            tags=application.state.tags_metadata_map,
         )
 
     @application.exception_handler(HTTPException)

src/framex/driver/auth.py

@@ -8,7 +8,7 @@
 from starlette.requests import Request
 
 from framex.config import settings
-from framex.consts import DOCS_URL
+from framex.consts import AUTH_COOKIE_NAME, DOCS_URL
 
 api_key_header = APIKeyHeader(name="Authorization", auto_error=False)
 
@@ -32,7 +32,7 @@ def auth_jwt(request: Request) -> bool:
     if not settings.auth.oauth:
         return False
 
-    token = request.cookies.get("token")
+    token = request.cookies.get(AUTH_COOKIE_NAME)
     if not token:
         return False
 
@@ -49,7 +49,7 @@ def auth_jwt(request: Request) -> bool:
 
 def authenticate(request: Request, api_key: str | None = Depends(api_key_header)) -> None:
     if settings.auth.oauth:
-        if token := request.cookies.get("token"):
+        if token := request.cookies.get(AUTH_COOKIE_NAME):
             try:
                 jwt.decode(
                     token,
@@ -120,7 +120,7 @@ async def oauth_callback(code: str) -> Response:
 
     res = RedirectResponse(url=DOCS_URL, status_code=status.HTTP_302_FOUND)
     res.set_cookie(
-        "token",
+        AUTH_COOKIE_NAME,
         create_jwt(user_info),
         httponly=True,
         samesite="lax",

src/framex/driver/ingress.py

@@ -60,6 +60,7 @@ def __init__(self, deployments: list[Any], plugin_apis: list["PluginApi"]) -> No
                     stream=plugin_api.stream,
                     direct_output=plugin_api.raw_response,
                     tags=plugin_api.tags,
+                    description=plugin_api.description,
                     **plugin_api.extend_kwargs,
                 )
 
@@ -73,6 +74,7 @@ def register_route(
         stream: bool = False,
         direct_output: bool = False,
         tags: list[str] | None = None,
+        description: str | None = None,
         auth_keys: list[str] | None = None,
         include_in_schema: bool = True,
         **kwargs: Any,
@@ -161,6 +163,7 @@ def _verify_api_key(request: Request, api_key: str | None = Depends(api_key_head
                 response_class=StreamingResponse if stream else JSONResponse,
                 dependencies=dependencies,
                 include_in_schema=include_in_schema,
+                description=description,
                 **kwargs,
             )
             methods_str = ",".join(m.upper() for m in methods)
@@ -188,6 +191,9 @@ def add_api_route(
         endpoint: Callable[..., Any],
         *,
         methods: list[str] | None = None,
+        tags: list[str] | None = None,
+        description: str | None = None,
+        include_in_schema: bool = True,
         **kwargs: Any,
     ) -> None:
         method_set: set[str] = {m.upper() for m in methods} if methods else {"GET"}
@@ -201,4 +207,22 @@ def add_api_route(
             ):
                 raise RuntimeError(f"Duplicate API route: {sorted(method_set)} {norm_path}")
 
-        app.add_api_route(path, endpoint, methods=list(method_set), **kwargs)
+        app.add_api_route(
+            path,
+            endpoint,
+            methods=list(method_set),  # type: ignore
+            tags=tags,  # type: ignore
+            include_in_schema=include_in_schema,
+            **kwargs,
+        )
+
+        if include_in_schema and tags:
+            names = list({tag["name"] for tag in app.state.tags_metadata_map})
+            for tag in tags:
+                if tag not in names:
+                    app.state.tags_metadata_map.append(
+                        {
+                            "name": tag,
+                            "description": description,
+                        },
+                    )

src/framex/plugin/base.py

@@ -73,3 +73,17 @@ async def _call_remote_api(self, api_name: str, **kwargs: Any) -> Any:
 
     def _post_call_remote_api_hook(self, data: Any) -> Any:
         return data
+
+
+def build_plugin_description(
+    author: str,
+    version: str,
+    description: str,
+    repo: str,
+) -> str:
+    return (
+        f"**Author**: {author}\n\n"
+        f"**Version**: {version}\n\n"
+        f"**Description**: {description}\n\n"
+        f"**Repo**: [{repo}]({repo})"
+    )

src/framex/plugin/model.py

@@ -34,6 +34,7 @@ class PluginApi(BaseModel):
     params: list[tuple[str, type[Any] | Callable[..., Any]]] = Field(default_factory=list)
     call_type: ApiType = ApiType.HTTP
     tags: list[str] | None = None
+    description: str | None = None
     stream: bool = False
     raw_response: bool = False
     extend_kwargs: dict[str, Any] = Field(default_factory=dict)

src/framex/plugin/on.py

@@ -9,6 +9,7 @@
 
 from framex.adapter import get_adapter
 from framex.consts import API_STR, PROXY_PLUGIN_NAME
+from framex.plugin.base import build_plugin_description
 from framex.plugin.model import ApiType, PluginApi, PluginDeployment
 from framex.utils import cache_decode, cache_encode, extract_method_params, plugin_to_deployment_name
 
@@ -42,11 +43,16 @@ def decorator(cls: type) -> type:
                     if func.__tags:
                         tags: list[str] = func.__tags
                     else:
-                        author: str = plugin.module.__plugin_meta__.author
-                        description = plugin.module.__plugin_meta__.description
-                        version: str = plugin.module.__plugin_meta__.version
-                        version = f"v{version}" if not version.startswith("v") else version
-                        tags = [f"{plugin.name} ({version}) by {author}: {description}"]
+                        tags = [plugin.name]
+
+                    version: str = plugin.module.__plugin_meta__.version
+                    version = f"v{version}" if not version.startswith("v") else version
+                    description = build_plugin_description(
+                        plugin.module.__plugin_meta__.author,
+                        version,
+                        plugin.module.__plugin_meta__.description,
+                        plugin.module.__plugin_meta__.url,
+                    )
 
                     plugin_apis.append(
                         PluginApi(
@@ -57,6 +63,7 @@ def decorator(cls: type) -> type:
                             params=params,
                             call_type=call_type,
                             tags=tags,
+                            description=description,
                             stream=func.__expose_stream,
                             raw_response=raw_response,
                             extend_kwargs=func.__kwargs,

src/framex/plugins/proxy/__init__.py

@@ -10,9 +10,10 @@
 
 from framex.adapter import get_adapter
 from framex.adapter.base import BaseAdapter
-from framex.consts import BACKEND_NAME, PROXY_FUNC_HTTP_PATH, PROXY_PLUGIN_NAME, VERSION
+from framex.consts import BACKEND_NAME, PROXY_FUNC_HTTP_PATH, PROXY_PLUGIN_NAME
 from framex.log import logger
 from framex.plugin import BasePlugin, PluginApi, PluginMetadata, on_register
+from framex.plugin.base import build_plugin_description
 from framex.plugin.model import ApiType
 from framex.plugin.on import on_request
 from framex.plugins.proxy.builder import (
@@ -23,15 +24,14 @@
     to_multipart_annotation,
     type_map,
 )
-from framex.plugins.proxy.config import ProxyPluginConfig, settings
+from framex.plugins.proxy.config import VERSION, ProxyPluginConfig, settings
 from framex.plugins.proxy.model import ProxyFunc, ProxyFuncHttpBody
 from framex.utils import cache_decode, cache_encode, shorten_str
 
 __plugin_meta__ = PluginMetadata(
     name="proxy",
     version=VERSION,
-    description="一个特殊的 framx proxy 插件, 充当透明代理。"
-    "它接收 API 请求并将其转发到已配置的外部 HTTP 端点,并将响应返回给调用者。",
+    description="proxy 是 FrameX 的核心系统插件, 作为透明代理转发 API 请求至外部 HTTP 端点并返回响应。",
     author="touale",
     url="https://github.com/touale/FrameX-kit",
     required_remote_apis=[],
@@ -170,6 +170,12 @@ async def _parse_openai_docs(self, url: str) -> None:
                     func_name="register_route",
                 )
                 handle = adapter.get_handle(PROXY_PLUGIN_NAME)
+                description = build_plugin_description(
+                    __plugin_meta__.author,
+                    f"v{__plugin_meta__.version}",
+                    __plugin_meta__.description,
+                    __plugin_meta__.url,
+                )
                 await adapter.call_func(
                     plugin_api,
                     path=path,
@@ -180,6 +186,7 @@ async def _parse_openai_docs(self, url: str) -> None:
                     stream=is_stream,
                     direct_output=True,
                     tags=[f"{__plugin_meta__.name}({url})"],
+                    description=description,
                 )
 
                 # Proxy api to map

src/framex/plugins/proxy/config.py

@@ -5,6 +5,8 @@
 from framex.config import AuthConfig
 from framex.plugin import get_plugin_config
 
+VERSION = "0.3.0"
+
 
 class ProxyUrlRuleConfig(BaseModel):
     enable: list[str] = Field(default_factory=list)

tests/driver/test_auth.py

@@ -11,7 +11,7 @@
 from starlette.requests import Request
 
 from framex.config import AuthConfig
-from framex.consts import DOCS_URL
+from framex.consts import AUTH_COOKIE_NAME, DOCS_URL
 from framex.driver.application import create_fastapi_application
 from framex.driver.auth import auth_jwt, authenticate, create_jwt, oauth_callback
 
@@ -219,6 +219,6 @@ def test_docs_accessible_with_valid_jwt(self):
                 JWT_SECRET,
                 algorithm="HS256",
             )
-            client.cookies.set("token", token)
+            client.cookies.set(AUTH_COOKIE_NAME, token)
             resp = client.get("/docs", follow_redirects=False)
             assert resp.status_code == status.HTTP_200_OK