star-openapi 0.9.2__tar.gz → 0.9.4__tar.gz

star_openapi-0.9.4/CHANGELOG.md

@@ -0,0 +1,19 @@
+## v0.9.4 2026-03-11
+
+- Add create_websocket_endpoint method compatible with cython build by @luolingchun in #9
+
+## v0.9.3 2026-03-02
+
+- APIRouter allows no slash suffix by @luolingchun in #7
+
+## v0.9.2 2026-01-26
+
+- Add parameter app to StarGroup by @luolingchun in #4
+
+## v0.9.1 2026-01-12
+
+- Support multi content type in request body and responses by @luolingchun in #2
+
+## v0.9.0 2026-01-04
+
+- first version

{star_openapi-0.9.2 → star_openapi-0.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: star-openapi
-Version: 0.9.2
+Version: 0.9.4
 Summary: A simple async API framework based on Starlette.
 Project-URL: Homepage, https://github.com/luolingchun/star-openapi
 Project-URL: Documentation, https://luolingchun.github.io/star-openapi

{star_openapi-0.9.2 → star_openapi-0.9.4}/examples/api_router_demo.py

@@ -40,11 +40,16 @@ async def delete_book(path: IdModel):
     return JSONResponse({"id": path.id})
 
 
-@api2.get("/")
+@api2.get("")
 async def get_api2():
     return JSONResponse({"message": "Hello World2"})
 
 
+@api2.websocket("")
+async def api2_websocket():
+    return JSONResponse({"message": "Hello World2"})
+
+
 api1.register_api(api2)
 
 app.register_api(api1)

{star_openapi-0.9.2 → star_openapi-0.9.4}/examples/form_demo.py

@@ -13,7 +13,7 @@ class BookModel(BaseModel):
 
 
 @app.post("/book")
-async def post_book(form: BookModel):
+async def create_book(form: BookModel):
     return JSONResponse(form.model_dump())
 
 

{star_openapi-0.9.2 → star_openapi-0.9.4}/examples/request_body_demo.py

@@ -21,7 +21,7 @@ request_body_json = RequestBody(
 
 
 @app.post("/json", request_body=request_body_json)
-async def get_json(request: Request, body: BookModel):
+async def post_json(request: Request, body: BookModel):
     print(request.headers.get("content-type"))
     print(body.model_json_schema())
     return JSONResponse({"message": "Hello World"})
@@ -38,7 +38,7 @@ request_body = RequestBody(
 
 
 @app.post("/text", request_body=request_body)
-async def get_csv(request: Request):
+async def post_csv(request: Request):
     print(request.headers.get("content-type"))
     data = await request.body()
     print(data)

{star_openapi-0.9.2 → star_openapi-0.9.4}/pyproject.toml

@@ -34,6 +34,10 @@ dependencies = [
     "click>=8.0.0",
 ]
 
+[project.urls]
+Homepage = "https://github.com/luolingchun/star-openapi"
+Documentation = "https://luolingchun.github.io/star-openapi"
+
 [project.optional-dependencies]
 full = [
     "itsdangerous",
@@ -49,21 +53,6 @@ rapipdf = ["star-openapi-rapipdf"]
 scalar = ["star-openapi-scalar"]
 elements = ["star-openapi-elements"]
 
-
-[project.urls]
-Homepage = "https://github.com/luolingchun/star-openapi"
-Documentation = "https://luolingchun.github.io/star-openapi"
-
-[project.scripts]
-star = "star_openapi.cli:main"
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[tool.hatch.version]
-path = "star_openapi/__version__.py"
-
 [dependency-groups]
 ty = ["ty"]
 ruff = ["ruff"]
@@ -89,6 +78,16 @@ dev = [
     "star-openapi-elements"
 ]
 
+[project.scripts]
+star = "star_openapi.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "star_openapi/__version__.py"
+
 [tool.uv]
 default-groups = "all"
 

star_openapi-0.9.4/star_openapi/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.9.4"

{star_openapi-0.9.2 → star_openapi-0.9.4}/star_openapi/cli.py

@@ -1,7 +1,5 @@
 import importlib
-import os
 import ssl
-import sys
 from typing import TYPE_CHECKING, Any, get_args
 
 import click
@@ -18,7 +16,7 @@ from uvicorn.config import (
 )
 from uvicorn.main import INTERFACE_CHOICES, LEVEL_CHOICES, LIFESPAN_CHOICES, print_version
 
-if TYPE_CHECKING:
+if TYPE_CHECKING:  # pragma: no cover
     from .openapi import OpenAPI
 
 
@@ -387,7 +385,7 @@ def run_command(
     app_dir: str,
     h11_max_incomplete_event_size: int | None,
     factory: bool,
-) -> None:
+) -> None:  # pragma: no cover
     app = ctx.parent.params["app"]
     uvicorn_run(
         app,
@@ -441,15 +439,9 @@ def run_command(
     )
 
 
-def _load_app(app=None, verbose=False):
-    if app is None:
-        return None
-
+def _load_app(app: str = "asgi:app", verbose: bool = False):
     try:
         module, attr = app.split(":")
-        path = os.getcwd()
-        if path not in sys.path:
-            sys.path.append(path)
         importlib.import_module(module)
     except Exception as e:
         if verbose:
@@ -545,9 +537,5 @@ cli = StarGroup(
 cli.add_command(run_command, "run")
 
 
-def main():
+def main():  # pragma: no cover
     cli.main()
-
-
-if __name__ == "__main__":
-    main()

{star_openapi-0.9.2 → star_openapi-0.9.4}/star_openapi/endpoint.py

@@ -5,6 +5,7 @@ from typing import Any, Type
 from pydantic import BaseModel
 from starlette.requests import Request
 from starlette.responses import Response
+from starlette.websockets import WebSocket
 
 from .request import _validate_request
 
@@ -37,3 +38,11 @@ def create_endpoint(
             return func(**kwargs)
 
     return endpoint
+
+
+def create_websocket_endpoint(func):
+    @wraps(func)
+    async def endpoint(websocket: WebSocket):
+        return await func(websocket)
+
+    return endpoint

star_openapi-0.9.4/star_openapi/models/__init__.py

@@ -0,0 +1,83 @@
+"""
+OpenAPI v3.1.0 schema types, created according to the specification:
+https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md
+
+The type orders are according to the contents of the specification:
+https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#table-of-contents
+"""
+
+from pydantic import BaseModel
+
+from .callback import Callback
+from .components import Components
+from .contact import Contact
+from .discriminator import Discriminator
+from .encoding import Encoding
+from .example import Example
+from .external_documentation import ExternalDocumentation
+from .file import UploadFile
+from .header import Header
+from .info import Info
+from .license import License
+from .link import Link
+from .media_type import MediaType
+from .oauth_flow import OAuthFlow
+from .oauth_flows import OAuthFlows
+from .operation import Operation
+from .parameter import Parameter
+from .parameter_in_type import ParameterInType
+from .path_item import PathItem
+from .paths import Paths
+from .reference import Reference
+from .request_body import RequestBody
+from .response import Response
+from .responses import Responses
+from .schema import Schema
+from .security_requirement import SecurityRequirement
+from .security_scheme import SecurityScheme
+from .server import Server
+from .server_variable import ServerVariable
+from .style_values import StyleValues
+from .tag import Tag
+from .validation_error import ValidationErrorModel
+from .xml import XML
+
+OPENAPI3_REF_PREFIX = "#/components/schemas"
+OPENAPI3_REF_TEMPLATE = OPENAPI3_REF_PREFIX + "/{model}"
+
+
+class OpenAPISpec(BaseModel):
+    """https://spec.openapis.org/oas/v3.1.0#openapi-object"""
+
+    openapi: str
+    info: Info
+    servers: list[Server] | None = None
+    paths: Paths
+    components: Components | None = None
+    security: list[SecurityRequirement] | None = None
+    tags: list[Tag] | None = None
+    externalDocs: ExternalDocumentation | None = None
+    webhooks: dict[str, PathItem | Reference] | None = None
+
+    model_config = {"extra": "allow"}
+
+
+class OAuthConfig(BaseModel):
+    """
+    https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/oauth2.md#oauth-20-configuration
+    """
+
+    clientId: str | None = None
+    clientSecret: str | None = None
+    realm: str | None = None
+    appName: str | None = None
+    scopeSeparator: str | None = None
+    scopes: str | None = None
+    additionalQueryStringParams: dict[str, str] | None = None
+    useBasicAuthenticationWithAccessCodeGrant: bool | None = False
+    usePkceWithAuthorizationCodeGrant: bool | None = False
+
+
+Encoding.model_rebuild()
+Operation.model_rebuild()
+PathItem.model_rebuild()

{star_openapi-0.9.2 → star_openapi-0.9.4}/star_openapi/openapi.py

@@ -9,11 +9,11 @@ from jinja2 import Template
 from pydantic import BaseModel, ValidationError
 from starlette.applications import Starlette
 from starlette.responses import HTMLResponse, JSONResponse
-from starlette.routing import Mount, Route, WebSocketRoute
+from starlette.routing import Mount, Route
 
 from .cli import cli
 from .config import Config
-from .endpoint import create_endpoint
+from .endpoint import create_endpoint, create_websocket_endpoint
 from .models import (
     OPENAPI3_REF_PREFIX,
     Components,
@@ -27,7 +27,7 @@ from .models import (
     Tag,
     ValidationErrorModel,
 )
-from .router import APIRouter
+from .router import APIRoute, APIRouter, APIWebSocketRoute
 from .templates import openapi_html_string
 from .types import ParametersTuple, ResponseDict
 from .utils import (
@@ -200,8 +200,6 @@ class OpenAPI(Starlette):
         if isinstance(self.info, dict):
             self.info = Info.model_validate(self.info)
         spec = OpenAPISpec(openapi=self.openapi_version, info=self.info, paths=self.paths)
-        spec.openapi = self.openapi_version
-        spec.info = self.info
 
         if self.severs:
             spec.servers = [Server(**server) if isinstance(server, dict) else server for server in self.severs]
@@ -238,8 +236,6 @@ class OpenAPI(Starlette):
         # Handle validation error response
         for rule, path_item in self.spec_json["paths"].items():
             for http_method, operation in path_item.items():
-                if operation.get("responses") is None:
-                    operation["responses"] = {}
                 if operation["responses"].get(self.validation_error_status):
                     continue
                 operation["responses"][self.validation_error_status] = {
@@ -255,6 +251,12 @@ class OpenAPI(Starlette):
                 }
 
     def register_api(self, api: APIRouter):
+        """
+        Register an APIRouter.
+
+        Args:
+            api: The APIBlueprint instance to register.
+        """
         for tag in api.tags:
             if tag.name not in self.tag_names:
                 # Append tag to the list of tags
@@ -270,16 +272,16 @@ class OpenAPI(Starlette):
 
         # Register the APIRouter with the current instance
         for route in api.routes:
-            if isinstance(route, Route):
-                path_with_prefix = api.url_prefix + route.path
+            if isinstance(route, APIRoute):
+                path_with_prefix = api.url_prefix + route.origin_path
                 self.router.add_route(
                     path=path_with_prefix,
                     endpoint=route.endpoint,
                     methods=route.methods,
                     name=route.name,
                 )
-            elif isinstance(route, WebSocketRoute):
-                path_with_prefix = api.url_prefix + route.path
+            elif isinstance(route, APIWebSocketRoute):
+                path_with_prefix = api.url_prefix + route.origin_path
                 self.router.add_websocket_route(path=path_with_prefix, endpoint=route.endpoint, name=route.name)
 
     def _collect_openapi_info(
@@ -375,6 +377,26 @@ class OpenAPI(Starlette):
         responses: ResponseDict | None = None,
         doc_ui: bool = True,
     ):
+        """
+        Decorator for defining a REST API endpoint with the HTTP GET method.
+        More information goto https://spec.openapis.org/oas/v3.1.0#operation-object
+
+        Args:
+            rule: The URL rule string.
+            name: The URL name string.
+            tags: Adds metadata to a single tag.
+            summary: A short summary of what the operation does.
+            description: A verbose explanation of the operation behavior.
+            external_docs: Additional external documentation for this operation.
+            operation_id: Unique string used to identify the operation.
+            deprecated: Declares this operation to be deprecated.
+            security: A declaration of which security mechanisms can be used for this operation.
+            servers: An alternative server array to service this operation.
+            openapi_extensions: Allows extensions to the OpenAPI Schema.
+            responses: API responses should be either a subclass of BaseModel, a dictionary, or None.
+            doc_ui: Declares this operation to be shown. Default to True.
+        """
+
         def decorator(func) -> Callable:
             header, cookie, path, query, form, body = self._collect_openapi_info(
                 rule,
@@ -417,6 +439,27 @@ class OpenAPI(Starlette):
         responses: ResponseDict | None = None,
         doc_ui: bool = True,
     ):
+        """
+        Decorator for defining a REST API endpoint with the HTTP POST method.
+        More information goto https://spec.openapis.org/oas/v3.1.0#operation-object
+
+        Args:
+            rule: The URL rule string.
+            name: The URL name string.
+            tags: Adds metadata to a single tag.
+            summary: A short summary of what the operation does.
+            description: A verbose explanation of the operation behavior.
+            external_docs: Additional external documentation for this operation.
+            operation_id: Unique string used to identify the operation.
+            deprecated: Declares this operation to be deprecated.
+            security: A declaration of which security mechanisms can be used for this operation.
+            servers: An alternative server array to service this operation.
+            openapi_extensions: Allows extensions to the OpenAPI Schema.
+            request_body: Advanced configuration in OpenAPI.
+            responses: API responses should be either a subclass of BaseModel, a dictionary, or None.
+            doc_ui: Declares this operation to be shown. Default to True.
+        """
+
         def decorator(func) -> Callable:
             header, cookie, path, query, form, body = self._collect_openapi_info(
                 rule,
@@ -460,6 +503,27 @@ class OpenAPI(Starlette):
         responses: ResponseDict | None = None,
         doc_ui: bool = True,
     ):
+        """
+        Decorator for defining a REST API endpoint with the HTTP PUT method.
+        More information goto https://spec.openapis.org/oas/v3.1.0#operation-object
+
+        Args:
+            rule: The URL rule string.
+            name: The URL name string.
+            tags: Adds metadata to a single tag.
+            summary: A short summary of what the operation does.
+            description: A verbose explanation of the operation behavior.
+            external_docs: Additional external documentation for this operation.
+            operation_id: Unique string used to identify the operation.
+            deprecated: Declares this operation to be deprecated.
+            security: A declaration of which security mechanisms can be used for this operation.
+            servers: An alternative server array to service this operation.
+            openapi_extensions: Allows extensions to the OpenAPI Schema.
+            request_body: Advanced configuration in OpenAPI.
+            responses: API responses should be either a subclass of BaseModel, a dictionary, or None.
+            doc_ui: Declares this operation to be shown. Default to True.
+        """
+
         def decorator(func) -> Callable:
             header, cookie, path, query, form, body = self._collect_openapi_info(
                 rule,
@@ -503,6 +567,27 @@ class OpenAPI(Starlette):
         responses: ResponseDict | None = None,
         doc_ui: bool = True,
     ):
+        """
+        Decorator for defining a REST API endpoint with the HTTP DELETE method.
+        More information goto https://spec.openapis.org/oas/v3.1.0#operation-object
+
+        Args:
+            rule: The URL rule string.
+            name: The URL name string.
+            tags: Adds metadata to a single tag.
+            summary: A short summary of what the operation does.
+            description: A verbose explanation of the operation behavior.
+            external_docs: Additional external documentation for this operation.
+            operation_id: Unique string used to identify the operation.
+            deprecated: Declares this operation to be deprecated.
+            security: A declaration of which security mechanisms can be used for this operation.
+            servers: An alternative server array to service this operation.
+            openapi_extensions: Allows extensions to the OpenAPI Schema.
+            request_body: Advanced configuration in OpenAPI.
+            responses: API responses should be either a subclass of BaseModel, a dictionary, or None.
+            doc_ui: Declares this operation to be shown. Default to True.
+        """
+
         def decorator(func) -> Callable:
             header, cookie, path, query, form, body = self._collect_openapi_info(
                 rule,
@@ -546,6 +631,27 @@ class OpenAPI(Starlette):
         responses: ResponseDict | None = None,
         doc_ui: bool = True,
     ):
+        """
+        Decorator for defining a REST API endpoint with the HTTP PATCH method.
+        More information goto https://spec.openapis.org/oas/v3.1.0#operation-object
+
+        Args:
+            rule: The URL rule string.
+            name: The URL name string.
+            tags: Adds metadata to a single tag.
+            summary: A short summary of what the operation does.
+            description: A verbose explanation of the operation behavior.
+            external_docs: Additional external documentation for this operation.
+            operation_id: Unique string used to identify the operation.
+            deprecated: Declares this operation to be deprecated.
+            security: A declaration of which security mechanisms can be used for this operation.
+            servers: An alternative server array to service this operation.
+            openapi_extensions: Allows extensions to the OpenAPI Schema.
+            request_body: Advanced configuration in OpenAPI.
+            responses: API responses should be either a subclass of BaseModel, a dictionary, or None.
+            doc_ui: Declares this operation to be shown. Default to True.
+        """
+
         def decorator(func) -> Callable:
             header, cookie, path, query, form, body = self._collect_openapi_info(
                 rule,
@@ -578,11 +684,9 @@ class OpenAPI(Starlette):
         name: str | None = None,
     ):
         def decorator(func) -> Callable:
-            self.add_websocket_route(
-                rule,
-                func,
-                name=name,
-            )
+            endpoint = create_websocket_endpoint(func)
+            self.add_websocket_route(rule, endpoint, name=name)
+
             return func
 
         return decorator

{star_openapi-0.9.2 → star_openapi-0.9.4}/star_openapi/request.py

@@ -43,19 +43,19 @@ async def _validate_header(request: Request, header: Type[BaseModel]):
     header_dict = {}
     model_properties = header.model_json_schema().get("properties", {})
     for model_field_key, model_field_value in header.model_fields.items():
-        key_title = model_field_key.replace("_", "-").title()
+        key_lower = model_field_key.lower()
         model_field_schema = model_properties.get(model_field_value.alias or model_field_key)
         if model_field_value.alias and header.model_config.get("populate_by_name"):
             key = model_field_value.alias
-            key_alias_title = model_field_value.alias.replace("_", "-").title()
-            value = request_headers.get(key_alias_title) or request_headers.get(key_title)
+            key_alias_title = model_field_value.alias.lower()
+            value = request_headers.get(key_alias_title) or request_headers.get(key_lower)
         elif model_field_value.alias:
             key = model_field_value.alias
-            key_alias_title = model_field_value.alias.replace("_", "-").title()
+            key_alias_title = model_field_value.alias.lower()
             value = request_headers.get(key_alias_title)
         else:
             key = model_field_key
-            value = request_headers[key_title]
+            value = request_headers.get(key_lower)
         if value is not None:
             header_dict[key] = value
         if model_field_schema.get("type") == "null":