Add support for operationID

docs/how_to_guides/index.rst

@@ -10,6 +10,7 @@ How to guides
    documenting.rst
    error_handling.rst
    headers_validation.rst
+   operation_id.rst
    querystring_validation.rst
    request_validation.rst
    response_validation.rst

docs/how_to_guides/operation_id.rst

@@ -0,0 +1,30 @@
+Operation IDs
+=============
+
+Operation IDs are used by certain OpenAPI clients when consuming the API spec. These are
+by default generated using the method and function name:
+
+.. code-block:: python
+
+    @app.get("/resource/")
+    async def resource():
+        ...
+
+    @app.post("/resource/")
+    async def create_resource():
+        ...
+
+would by default assign Operation IDs of ``get_resource`` and ``post_create_resource``
+respectively. To have more fine-grained control, part of the Operation ID can be
+overridden:
+
+.. code-block:: python
+
+    from quart_schema import operation_id
+
+    @app.post("/resource/")
+    @operation_id("make_resource")
+    async def create_resource():
+        ...
+
+which would assign an Operation ID of ``post_make_resource`` to the route.

src/quart_schema/__init__.py

@@ -5,7 +5,7 @@
     document_request,
     document_response,
 )
-from .extension import deprecate, hide, QuartSchema, security_scheme, tag
+from .extension import deprecate, hide, QuartSchema, operation_id, security_scheme, tag
 from .mixins import SchemaValidationError
 from .openapi import (
     APIKeySecurityScheme,
@@ -49,6 +49,7 @@
     "License",
     "OAuth2SecurityScheme",
     "OpenIdSecurityScheme",
+    "operation_id",
     "QuartSchema",
     "RequestSchemaValidationError",
     "ResponseReturnValue",

src/quart_schema/extension.py

@@ -57,6 +57,7 @@
 
 QUART_SCHEMA_HIDDEN_ATTRIBUTE = "_quart_schema_hidden"
 QUART_SCHEMA_TAG_ATTRIBUTE = "_quart_schema_tag"
+QUART_SCHEMA_OPERATION_ID_ATTRIBUTE = "_quart_schema_operation_id"
 QUART_SCHEMA_SECURITY_ATTRIBUTE = "_quart_schema_security_tag"
 QUART_SCHEMA_DEPRECATED = "_quart_schema_deprecated"
 REF_PREFIX = "#/components/schemas/"
@@ -359,6 +360,25 @@ async def decorator(result: ResponseReturnValue) -> Response:
     return decorator
 
 
+def operation_id(operationid: str) -> Callable:
+    """Override the operationId of the route.
+
+    This allows for overriding the operationId, which is normally calculated from the
+    function name. The HTTP method will still be prepended to the overridden name.
+
+    Arguments:
+        operationid: The operation ID to associate.
+
+    """
+
+    def decorator(func: Callable) -> Callable:
+        setattr(func, QUART_SCHEMA_OPERATION_ID_ATTRIBUTE, str(operationid))
+
+        return func
+
+    return decorator
+
+
 def tag(tags: Iterable[str]) -> Callable:
     """Add tag names to the route.
 
@@ -531,7 +551,15 @@ def _build_path(func: Callable, rule: Rule, app: Quart) -> Tuple[dict, dict]:
     for method in rule.methods:
         if method == "HEAD" or (method == "OPTIONS" and rule.provide_automatic_options):  # type: ignore # noqa: E501
             continue
-        paths[path][method.lower()] = operation_object
+
+        per_method_operation_object = operation_object.copy()
+
+        if getattr(func, QUART_SCHEMA_OPERATION_ID_ATTRIBUTE, None) is not None:
+            per_method_operation_object["operationId"] = f"{method.lower()}_{getattr(func, QUART_SCHEMA_OPERATION_ID_ATTRIBUTE)}"
+        else:
+            per_method_operation_object["operationId"] = f"{method.lower()}_{func.__name__}"
+
+        paths[path][method.lower()] = per_method_operation_object
     return paths, components
 
 

tests/test_openapi.py

@@ -7,14 +7,14 @@
 from quart_schema import (
     deprecate,
     QuartSchema,
+    operation_id,
     security_scheme,
     validate_headers,
     validate_querystring,
     validate_request,
     validate_response,
 )
 
-
 @dataclass
 class QueryItem:
     count_le: Optional[int] = Field(description="count_le description")
@@ -61,6 +61,7 @@ async def read_item() -> Tuple[Result, int, Headers]:
     @app.post("/")
     @validate_request(Details)
     @validate_response(Result, 201, Headers)
+    @operation_id("make_item")
     @deprecate()
     async def create_item() -> Tuple[Result, int, Headers]:
         return Result(name="bob"), 201, Headers(x_name="jeff")
@@ -81,6 +82,7 @@ async def ws() -> None:
                     "summary": "Summary",
                     "description": "Multi-line\ndescription.\n\nThis is a new paragraph\n\n    "
                     "And this is an indented codeblock.\n\nAnd another paragraph.",
+                    "operationId": "get_read_item",
                     "parameters": [
                         {
                             "in": "query",
@@ -125,6 +127,7 @@ async def ws() -> None:
                 },
                 "post": {
                     "deprecated": True,
+                    "operationId": "post_make_item",
                     "parameters": [],
                     "requestBody": {
                         "content": {