APIRouter

APIRouter

Bases: Router

Source code in star_openapi/router.py

class APIRouter(Router):
    def __init__(
        self,
        *,
        url_prefix: str = "",
        tags: list[Tag | dict[str, Any]] | None = None,
        security: list[dict[str, list[str]]] | None = None,
        operation_id_callback: Callable = get_operation_id_for_path,
        responses: ResponseDict | None = None,
        doc_ui: bool = True,
        **kwargs,
    ):
        """
        Based on Router

        Args:
            url_prefix: URL prefix that will be added before all route paths.
            tags: APIRouter tags for every API.
            security: APIRouter security for every API.
            operation_id_callback: Callback function for custom operation_id generation.
            responses: API responses should be either a subclass of BaseModel, a dictionary, or None.
            doc_ui: Enable OpenAPI document UI (Swagger UI, Redoc, etc.). Defaults to True.
            **kwargs: Starlette Router kwargs
        """
        super().__init__(**kwargs)

        self.url_prefix = url_prefix
        self.paths: dict[str, Any] = {}
        self.components_schemas: dict[str, Any] = {}
        self.tags: list[Tag] = []
        self.api_tags = tags or []
        self.tag_names: list[str] = []
        self.security = security or []
        self.operation_id_callback = operation_id_callback
        self.responses = convert_responses_key_to_string(responses or {})
        self.doc_ui = doc_ui

    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
                self.tags.append(tag)
                # Append tag name to the list of tag names
                self.tag_names.append(tag.name)

        prefixed_paths = {f"{self.url_prefix.rstrip('/')}{k}": v for k, v in api.paths.items()}
        self.paths.update(**prefixed_paths)

        # Update component schemas with the APIRouter's component schemas
        self.components_schemas.update(**api.components_schemas)

        # Register the APIRouter with the current instance
        for route in api.routes:
            if isinstance(route, Route):
                path_with_prefix = api.url_prefix + route.path
                self.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
                self.add_websocket_route(path=path_with_prefix, endpoint=route.endpoint, name=route.name)

    def _collect_openapi_info(
        self,
        rule: str,
        func: FunctionType,
        *,
        tags: list[Tag | dict[str, Any]] | None = None,
        summary: str | None = None,
        description: str | None = None,
        external_docs: ExternalDocumentation | dict[str, Any] | None = None,
        operation_id: str | None = None,
        deprecated: bool | None = None,
        security: list[dict[str, list[Any]]] | None = None,
        servers: list[Server | dict[str, Any]] | None = None,
        openapi_extensions: dict[str, Any] | None = None,
        request_body: RequestBody | dict[str, Any] | None = None,
        responses: ResponseDict | None = None,
        doc_ui: bool = True,
        method: str = HTTPMethod.GET,
    ) -> ParametersTuple:
        if self.doc_ui and doc_ui:
            # Convert key to string
            endpoint_responses = convert_responses_key_to_string(responses or {})

            # Global response: combine API responses
            combine_responses = {**self.responses, **endpoint_responses}

            # Create operation
            operation = get_operation(
                func,
                summary=summary,
                description=description,
                openapi_extensions=openapi_extensions,
            )

            # Set external docs
            if external_docs:
                operation.externalDocs = external_docs

            # Unique string used to identify the operation.
            operation.operationId = operation_id or self.operation_id_callback(
                url_prefix=self.url_prefix, name=func.__name__, path=rule, method=method
            )

            # Only set `deprecated` if True, otherwise leave it as None
            if deprecated is not None:
                operation.deprecated = deprecated

            # Add security
            _security = (security or []) + self.security or None
            if _security:
                operation.security = _security

            # Add servers
            if servers:
                operation.servers = servers

            # Store tags
            tags = (tags or []) + self.api_tags
            parse_and_store_tags(tags, self.tags, self.tag_names, operation)

            # Parse rule: merge url_prefix
            uri = parse_rule(rule, url_prefix=self.url_prefix)

            # Parse method
            parse_method(uri, method, self.paths, operation)

            if isinstance(request_body, dict):
                request_body = RequestBody(**request_body)

            # Parse response
            get_responses(combine_responses, self.components_schemas, operation)

            # Parse parameters
            return parse_parameters(
                func,
                components_schemas=self.components_schemas,
                operation=operation,
                request_body=request_body,
            )
        else:
            return parse_parameters(func, doc_ui=False)

    def get(
        self,
        rule: str,
        *,
        name: str | None = None,
        tags: list[Tag | dict[str, Any]] | None = None,
        summary: str | None = None,
        description: str | None = None,
        external_docs: ExternalDocumentation | dict[str, Any] | None = None,
        operation_id: str | None = None,
        deprecated: bool | None = None,
        security: list[dict[str, list[Any]]] | None = None,
        servers: list[Server | dict[str, Any]] | None = None,
        openapi_extensions: dict[str, Any] | None = None,
        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.
            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,
                func,
                tags=tags,
                summary=summary,
                description=description,
                external_docs=external_docs,
                operation_id=operation_id,
                deprecated=deprecated,
                security=security,
                servers=servers,
                openapi_extensions=openapi_extensions,
                responses=responses,
                doc_ui=doc_ui,
                method=HTTPMethod.GET,
            )
            endpoint = create_endpoint(func, header, cookie, path, query, form, body)
            self.add_route(rule, endpoint, methods=["GET"], name=name, include_in_schema=False)

            return func

        return decorator

    def post(
        self,
        rule: str,
        *,
        name: str | None = None,
        tags: list[Tag | dict[str, Any]] | None = None,
        summary: str | None = None,
        description: str | None = None,
        external_docs: ExternalDocumentation | dict[str, Any] | None = None,
        operation_id: str | None = None,
        deprecated: bool | None = None,
        security: list[dict[str, list[Any]]] | None = None,
        servers: list[Server | dict[str, Any]] | None = None,
        openapi_extensions: dict[str, Any] | None = None,
        request_body: RequestBody | dict[str, Any] | None = None,
        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.
            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,
                func,
                tags=tags,
                summary=summary,
                description=description,
                external_docs=external_docs,
                operation_id=operation_id,
                deprecated=deprecated,
                security=security,
                servers=servers,
                openapi_extensions=openapi_extensions,
                request_body=request_body,
                responses=responses,
                doc_ui=doc_ui,
                method=HTTPMethod.POST,
            )
            endpoint = create_endpoint(func, header, cookie, path, query, form, body)
            self.add_route(rule, endpoint, methods=["POST"], name=name, include_in_schema=False)

            return func

        return decorator

    def put(
        self,
        rule: str,
        *,
        name: str | None = None,
        tags: list[Tag | dict[str, Any]] | None = None,
        summary: str | None = None,
        description: str | None = None,
        external_docs: ExternalDocumentation | dict[str, Any] | None = None,
        operation_id: str | None = None,
        deprecated: bool | None = None,
        security: list[dict[str, list[Any]]] | None = None,
        servers: list[Server | dict[str, Any]] | None = None,
        openapi_extensions: dict[str, Any] | None = None,
        request_body: RequestBody | dict[str, Any] | None = None,
        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.
            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,
                func,
                tags=tags,
                summary=summary,
                description=description,
                external_docs=external_docs,
                operation_id=operation_id,
                deprecated=deprecated,
                security=security,
                servers=servers,
                openapi_extensions=openapi_extensions,
                request_body=request_body,
                responses=responses,
                doc_ui=doc_ui,
                method=HTTPMethod.PUT,
            )
            endpoint = create_endpoint(func, header, cookie, path, query, form, body)
            self.add_route(rule, endpoint, methods=["PUT"], name=name, include_in_schema=False)

            return func

        return decorator

    def delete(
        self,
        rule: str,
        *,
        name: str | None = None,
        tags: list[Tag | dict[str, Any]] | None = None,
        summary: str | None = None,
        description: str | None = None,
        external_docs: ExternalDocumentation | dict[str, Any] | None = None,
        operation_id: str | None = None,
        deprecated: bool | None = None,
        security: list[dict[str, list[Any]]] | None = None,
        servers: list[Server | dict[str, Any]] | None = None,
        openapi_extensions: dict[str, Any] | None = None,
        request_body: RequestBody | dict[str, Any] | None = None,
        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.
            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,
                func,
                tags=tags,
                summary=summary,
                description=description,
                external_docs=external_docs,
                operation_id=operation_id,
                deprecated=deprecated,
                security=security,
                servers=servers,
                openapi_extensions=openapi_extensions,
                request_body=request_body,
                responses=responses,
                doc_ui=doc_ui,
                method=HTTPMethod.DELETE,
            )
            endpoint = create_endpoint(func, header, cookie, path, query, form, body)
            self.add_route(rule, endpoint, methods=["DELETE"], name=name, include_in_schema=False)

            return func

        return decorator

    def patch(
        self,
        rule: str,
        *,
        name: str | None = None,
        tags: list[Tag | dict[str, Any]] | None = None,
        summary: str | None = None,
        description: str | None = None,
        external_docs: ExternalDocumentation | dict[str, Any] | None = None,
        operation_id: str | None = None,
        deprecated: bool | None = None,
        security: list[dict[str, list[Any]]] | None = None,
        servers: list[Server | dict[str, Any]] | None = None,
        openapi_extensions: dict[str, Any] | None = None,
        request_body: RequestBody | dict[str, Any] | None = None,
        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.
            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,
                func,
                tags=tags,
                summary=summary,
                description=description,
                external_docs=external_docs,
                operation_id=operation_id,
                deprecated=deprecated,
                security=security,
                servers=servers,
                openapi_extensions=openapi_extensions,
                request_body=request_body,
                responses=responses,
                doc_ui=doc_ui,
                method=HTTPMethod.PATCH,
            )
            endpoint = create_endpoint(func, header, cookie, path, query, form, body)
            self.add_route(rule, endpoint, methods=["PATCH"], name=name, include_in_schema=False)

            return func

        return decorator

    def websocket(
        self,
        rule: str,
        *,
        name: str | None = None,
    ):
        def decorator(func) -> Callable:
            self.add_websocket_route(
                rule,
                func,
                name=name,
            )
            return func

        return decorator

__init__(*, url_prefix='', tags=None, security=None, operation_id_callback=get_operation_id_for_path, responses=None, doc_ui=True, **kwargs)

Based on Router

Parameters:

Name	Type	Description	Default
url_prefix	str	URL prefix that will be added before all route paths.	''
tags	list[Tag | dict[str, Any]] | None	APIRouter tags for every API.	None
security	list[dict[str, list[str]]] | None	APIRouter security for every API.	None
operation_id_callback	Callable	Callback function for custom operation_id generation.	get_operation_id_for_path
responses	ResponseDict | None	API responses should be either a subclass of BaseModel, a dictionary, or None.	None
doc_ui	bool	Enable OpenAPI document UI (Swagger UI, Redoc, etc.). Defaults to True.	True
**kwargs		Starlette Router kwargs	{}

Source code in star_openapi/router.py

def __init__(
    self,
    *,
    url_prefix: str = "",
    tags: list[Tag | dict[str, Any]] | None = None,
    security: list[dict[str, list[str]]] | None = None,
    operation_id_callback: Callable = get_operation_id_for_path,
    responses: ResponseDict | None = None,
    doc_ui: bool = True,
    **kwargs,
):
    """
    Based on Router

    Args:
        url_prefix: URL prefix that will be added before all route paths.
        tags: APIRouter tags for every API.
        security: APIRouter security for every API.
        operation_id_callback: Callback function for custom operation_id generation.
        responses: API responses should be either a subclass of BaseModel, a dictionary, or None.
        doc_ui: Enable OpenAPI document UI (Swagger UI, Redoc, etc.). Defaults to True.
        **kwargs: Starlette Router kwargs
    """
    super().__init__(**kwargs)

    self.url_prefix = url_prefix
    self.paths: dict[str, Any] = {}
    self.components_schemas: dict[str, Any] = {}
    self.tags: list[Tag] = []
    self.api_tags = tags or []
    self.tag_names: list[str] = []
    self.security = security or []
    self.operation_id_callback = operation_id_callback
    self.responses = convert_responses_key_to_string(responses or {})
    self.doc_ui = doc_ui

delete(rule, *, name=None, tags=None, summary=None, description=None, external_docs=None, operation_id=None, deprecated=None, security=None, servers=None, openapi_extensions=None, request_body=None, responses=None, doc_ui=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

Parameters:

Name	Type	Description	Default
rule	str	The URL rule string.	required
tags	list[Tag | dict[str, Any]] | None	Adds metadata to a single tag.	None
summary	str | None	A short summary of what the operation does.	None
description	str | None	A verbose explanation of the operation behavior.	None
external_docs	ExternalDocumentation | dict[str, Any] | None	Additional external documentation for this operation.	None
operation_id	str | None	Unique string used to identify the operation.	None
deprecated	bool | None	Declares this operation to be deprecated.	None
security	list[dict[str, list[Any]]] | None	A declaration of which security mechanisms can be used for this operation.	None
servers	list[Server | dict[str, Any]] | None	An alternative server array to service this operation.	None
openapi_extensions	dict[str, Any] | None	Allows extensions to the OpenAPI Schema.	None
responses	ResponseDict | None	API responses should be either a subclass of BaseModel, a dictionary, or None.	None
doc_ui	bool	Declares this operation to be shown. Default to True.	True

Source code in star_openapi/router.py

def delete(
    self,
    rule: str,
    *,
    name: str | None = None,
    tags: list[Tag | dict[str, Any]] | None = None,
    summary: str | None = None,
    description: str | None = None,
    external_docs: ExternalDocumentation | dict[str, Any] | None = None,
    operation_id: str | None = None,
    deprecated: bool | None = None,
    security: list[dict[str, list[Any]]] | None = None,
    servers: list[Server | dict[str, Any]] | None = None,
    openapi_extensions: dict[str, Any] | None = None,
    request_body: RequestBody | dict[str, Any] | None = None,
    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.
        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,
            func,
            tags=tags,
            summary=summary,
            description=description,
            external_docs=external_docs,
            operation_id=operation_id,
            deprecated=deprecated,
            security=security,
            servers=servers,
            openapi_extensions=openapi_extensions,
            request_body=request_body,
            responses=responses,
            doc_ui=doc_ui,
            method=HTTPMethod.DELETE,
        )
        endpoint = create_endpoint(func, header, cookie, path, query, form, body)
        self.add_route(rule, endpoint, methods=["DELETE"], name=name, include_in_schema=False)

        return func

    return decorator

get(rule, *, name=None, tags=None, summary=None, description=None, external_docs=None, operation_id=None, deprecated=None, security=None, servers=None, openapi_extensions=None, responses=None, doc_ui=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

Parameters:

Name	Type	Description	Default
rule	str	The URL rule string.	required
tags	list[Tag | dict[str, Any]] | None	Adds metadata to a single tag.	None
summary	str | None	A short summary of what the operation does.	None
description	str | None	A verbose explanation of the operation behavior.	None
external_docs	ExternalDocumentation | dict[str, Any] | None	Additional external documentation for this operation.	None
operation_id	str | None	Unique string used to identify the operation.	None
deprecated	bool | None	Declares this operation to be deprecated.	None
security	list[dict[str, list[Any]]] | None	A declaration of which security mechanisms can be used for this operation.	None
servers	list[Server | dict[str, Any]] | None	An alternative server array to service this operation.	None
openapi_extensions	dict[str, Any] | None	Allows extensions to the OpenAPI Schema.	None
responses	ResponseDict | None	API responses should be either a subclass of BaseModel, a dictionary, or None.	None
doc_ui	bool	Declares this operation to be shown. Default to True.	True

Source code in star_openapi/router.py

def get(
    self,
    rule: str,
    *,
    name: str | None = None,
    tags: list[Tag | dict[str, Any]] | None = None,
    summary: str | None = None,
    description: str | None = None,
    external_docs: ExternalDocumentation | dict[str, Any] | None = None,
    operation_id: str | None = None,
    deprecated: bool | None = None,
    security: list[dict[str, list[Any]]] | None = None,
    servers: list[Server | dict[str, Any]] | None = None,
    openapi_extensions: dict[str, Any] | None = None,
    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.
        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,
            func,
            tags=tags,
            summary=summary,
            description=description,
            external_docs=external_docs,
            operation_id=operation_id,
            deprecated=deprecated,
            security=security,
            servers=servers,
            openapi_extensions=openapi_extensions,
            responses=responses,
            doc_ui=doc_ui,
            method=HTTPMethod.GET,
        )
        endpoint = create_endpoint(func, header, cookie, path, query, form, body)
        self.add_route(rule, endpoint, methods=["GET"], name=name, include_in_schema=False)

        return func

    return decorator

patch(rule, *, name=None, tags=None, summary=None, description=None, external_docs=None, operation_id=None, deprecated=None, security=None, servers=None, openapi_extensions=None, request_body=None, responses=None, doc_ui=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

Parameters:

Name	Type	Description	Default
rule	str	The URL rule string.	required
tags	list[Tag | dict[str, Any]] | None	Adds metadata to a single tag.	None
summary	str | None	A short summary of what the operation does.	None
description	str | None	A verbose explanation of the operation behavior.	None
external_docs	ExternalDocumentation | dict[str, Any] | None	Additional external documentation for this operation.	None
operation_id	str | None	Unique string used to identify the operation.	None
deprecated	bool | None	Declares this operation to be deprecated.	None
security	list[dict[str, list[Any]]] | None	A declaration of which security mechanisms can be used for this operation.	None
servers	list[Server | dict[str, Any]] | None	An alternative server array to service this operation.	None
openapi_extensions	dict[str, Any] | None	Allows extensions to the OpenAPI Schema.	None
responses	ResponseDict | None	API responses should be either a subclass of BaseModel, a dictionary, or None.	None
doc_ui	bool	Declares this operation to be shown. Default to True.	True

Source code in star_openapi/router.py

def patch(
    self,
    rule: str,
    *,
    name: str | None = None,
    tags: list[Tag | dict[str, Any]] | None = None,
    summary: str | None = None,
    description: str | None = None,
    external_docs: ExternalDocumentation | dict[str, Any] | None = None,
    operation_id: str | None = None,
    deprecated: bool | None = None,
    security: list[dict[str, list[Any]]] | None = None,
    servers: list[Server | dict[str, Any]] | None = None,
    openapi_extensions: dict[str, Any] | None = None,
    request_body: RequestBody | dict[str, Any] | None = None,
    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.
        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,
            func,
            tags=tags,
            summary=summary,
            description=description,
            external_docs=external_docs,
            operation_id=operation_id,
            deprecated=deprecated,
            security=security,
            servers=servers,
            openapi_extensions=openapi_extensions,
            request_body=request_body,
            responses=responses,
            doc_ui=doc_ui,
            method=HTTPMethod.PATCH,
        )
        endpoint = create_endpoint(func, header, cookie, path, query, form, body)
        self.add_route(rule, endpoint, methods=["PATCH"], name=name, include_in_schema=False)

        return func

    return decorator

post(rule, *, name=None, tags=None, summary=None, description=None, external_docs=None, operation_id=None, deprecated=None, security=None, servers=None, openapi_extensions=None, request_body=None, responses=None, doc_ui=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

Parameters:

Name	Type	Description	Default
rule	str	The URL rule string.	required
tags	list[Tag | dict[str, Any]] | None	Adds metadata to a single tag.	None
summary	str | None	A short summary of what the operation does.	None
description	str | None	A verbose explanation of the operation behavior.	None
external_docs	ExternalDocumentation | dict[str, Any] | None	Additional external documentation for this operation.	None
operation_id	str | None	Unique string used to identify the operation.	None
deprecated	bool | None	Declares this operation to be deprecated.	None
security	list[dict[str, list[Any]]] | None	A declaration of which security mechanisms can be used for this operation.	None
servers	list[Server | dict[str, Any]] | None	An alternative server array to service this operation.	None
openapi_extensions	dict[str, Any] | None	Allows extensions to the OpenAPI Schema.	None
responses	ResponseDict | None	API responses should be either a subclass of BaseModel, a dictionary, or None.	None
doc_ui	bool	Declares this operation to be shown. Default to True.	True

Source code in star_openapi/router.py

def post(
    self,
    rule: str,
    *,
    name: str | None = None,
    tags: list[Tag | dict[str, Any]] | None = None,
    summary: str | None = None,
    description: str | None = None,
    external_docs: ExternalDocumentation | dict[str, Any] | None = None,
    operation_id: str | None = None,
    deprecated: bool | None = None,
    security: list[dict[str, list[Any]]] | None = None,
    servers: list[Server | dict[str, Any]] | None = None,
    openapi_extensions: dict[str, Any] | None = None,
    request_body: RequestBody | dict[str, Any] | None = None,
    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.
        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,
            func,
            tags=tags,
            summary=summary,
            description=description,
            external_docs=external_docs,
            operation_id=operation_id,
            deprecated=deprecated,
            security=security,
            servers=servers,
            openapi_extensions=openapi_extensions,
            request_body=request_body,
            responses=responses,
            doc_ui=doc_ui,
            method=HTTPMethod.POST,
        )
        endpoint = create_endpoint(func, header, cookie, path, query, form, body)
        self.add_route(rule, endpoint, methods=["POST"], name=name, include_in_schema=False)

        return func

    return decorator

put(rule, *, name=None, tags=None, summary=None, description=None, external_docs=None, operation_id=None, deprecated=None, security=None, servers=None, openapi_extensions=None, request_body=None, responses=None, doc_ui=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

Parameters:

Name	Type	Description	Default
rule	str	The URL rule string.	required
tags	list[Tag | dict[str, Any]] | None	Adds metadata to a single tag.	None
summary	str | None	A short summary of what the operation does.	None
description	str | None	A verbose explanation of the operation behavior.	None
external_docs	ExternalDocumentation | dict[str, Any] | None	Additional external documentation for this operation.	None
operation_id	str | None	Unique string used to identify the operation.	None
deprecated	bool | None	Declares this operation to be deprecated.	None
security	list[dict[str, list[Any]]] | None	A declaration of which security mechanisms can be used for this operation.	None
servers	list[Server | dict[str, Any]] | None	An alternative server array to service this operation.	None
openapi_extensions	dict[str, Any] | None	Allows extensions to the OpenAPI Schema.	None
responses	ResponseDict | None	API responses should be either a subclass of BaseModel, a dictionary, or None.	None
doc_ui	bool	Declares this operation to be shown. Default to True.	True

Source code in star_openapi/router.py

def put(
    self,
    rule: str,
    *,
    name: str | None = None,
    tags: list[Tag | dict[str, Any]] | None = None,
    summary: str | None = None,
    description: str | None = None,
    external_docs: ExternalDocumentation | dict[str, Any] | None = None,
    operation_id: str | None = None,
    deprecated: bool | None = None,
    security: list[dict[str, list[Any]]] | None = None,
    servers: list[Server | dict[str, Any]] | None = None,
    openapi_extensions: dict[str, Any] | None = None,
    request_body: RequestBody | dict[str, Any] | None = None,
    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.
        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,
            func,
            tags=tags,
            summary=summary,
            description=description,
            external_docs=external_docs,
            operation_id=operation_id,
            deprecated=deprecated,
            security=security,
            servers=servers,
            openapi_extensions=openapi_extensions,
            request_body=request_body,
            responses=responses,
            doc_ui=doc_ui,
            method=HTTPMethod.PUT,
        )
        endpoint = create_endpoint(func, header, cookie, path, query, form, body)
        self.add_route(rule, endpoint, methods=["PUT"], name=name, include_in_schema=False)

        return func

    return decorator

register_api(api)

Register an APIRouter.

Parameters:

Name	Type	Description	Default
api	APIRouter	The APIBlueprint instance to register.	required

Source code in star_openapi/router.py

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
            self.tags.append(tag)
            # Append tag name to the list of tag names
            self.tag_names.append(tag.name)

    prefixed_paths = {f"{self.url_prefix.rstrip('/')}{k}": v for k, v in api.paths.items()}
    self.paths.update(**prefixed_paths)

    # Update component schemas with the APIRouter's component schemas
    self.components_schemas.update(**api.components_schemas)

    # Register the APIRouter with the current instance
    for route in api.routes:
        if isinstance(route, Route):
            path_with_prefix = api.url_prefix + route.path
            self.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
            self.add_websocket_route(path=path_with_prefix, endpoint=route.endpoint, name=route.name)