Add the ability to customize the title and description of the api version parameter (#274)

Fix #272

Author: zmievsa

CHANGELOG.md

@@ -5,6 +5,12 @@ Please follow [the Keep a Changelog standard](https://keepachangelog.com/en/1.0.
 
 ## [Unreleased]
 
+## [5.3.0]
+
+### Added
+
+* `api_version_title` and `api_version_description` arguments to `Cadwyn` to allow customizing the API version parameter in the OpenAPI schema
+
 ## [5.2.2]
 
 ### Fixed

cadwyn/applications.py

@@ -4,7 +4,7 @@
 from datetime import date
 from logging import getLogger
 from pathlib import Path
-from typing import TYPE_CHECKING, Annotated, Any, Union, cast
+from typing import TYPE_CHECKING, Annotated, Any, Optional, Union, cast
 
 import fastapi
 from fastapi import APIRouter, FastAPI, HTTPException, routing
@@ -71,6 +71,8 @@ def __init__(
         api_version_format: APIVersionFormat = "date",
         api_version_parameter_name: str = "x-api-version",
         api_version_default_value: Union[str, None, Callable[[Request], Awaitable[str]]] = None,
+        api_version_title: Optional[str] = None,
+        api_version_description: Optional[str] = None,
         versioning_middleware_class: type[VersionPickingMiddleware] = VersionPickingMiddleware,
         changelog_url: Union[str, None] = "/changelog",
         include_changelog_url_in_schema: bool = True,
@@ -207,6 +209,8 @@ def __init__(
         self.api_version_format = api_version_format
         self.api_version_parameter_name = api_version_parameter_name
         self.api_version_pythonic_parameter_name = api_version_parameter_name.replace("-", "_")
+        self.api_version_title = api_version_title
+        self.api_version_description = api_version_description
         if api_version_location == "custom_header":
             self._api_version_manager = HeaderVersionManager(api_version_parameter_name=api_version_parameter_name)
             self._api_version_fastapi_depends_class = fastapi.Header
@@ -465,6 +469,8 @@ def _add_versioned_routers(
                             default_value=version,
                             fastapi_depends_class=self._api_version_fastapi_depends_class,
                             validation_data_type=self.api_version_validation_data_type,
+                            title=self.api_version_title,
+                            description=self.api_version_description,
                         )
                     )
                 ],

cadwyn/middleware.py

@@ -5,7 +5,7 @@
 import re
 from collections.abc import Awaitable, Callable
 from contextvars import ContextVar
-from typing import Annotated, Any, Literal, Protocol, Union
+from typing import Annotated, Any, Literal, Optional, Protocol, Union
 
 import fastapi
 from fastapi import Request
@@ -58,6 +58,8 @@ def _generate_api_version_dependency(
     default_value: str,
     fastapi_depends_class: Callable[..., Any],
     validation_data_type: Any,
+    title: Optional[str] = None,
+    description: Optional[str] = None,
 ):
     def api_version_dependency(**kwargs: Any):
         # TODO: What do I return?
@@ -69,7 +71,12 @@ def api_version_dependency(**kwargs: Any):
                 api_version_pythonic_parameter_name,
                 inspect.Parameter.KEYWORD_ONLY,
                 annotation=Annotated[
-                    validation_data_type, fastapi_depends_class(openapi_examples={"default": {"value": default_value}})
+                    validation_data_type,
+                    fastapi_depends_class(
+                        openapi_examples={"default": {"value": default_value}},
+                        title=title,
+                        description=description,
+                    ),
                 ],
                 # Path-based parameters do not support a default value in FastAPI :(
                 default=default_value if fastapi_depends_class != fastapi.Path else inspect.Signature.empty,

docs/concepts/where_to_put_the_version_and_how_to_format_it.md renamed to docs/concepts/api_version_parameter.md

@@ -1,4 +1,4 @@
-# Where to put the version and how to format it
+# API Version Parameter
 
 Cadwyn adds another routing layer to FastAPI by default: by version parameter. This means that before FastAPI tries to route us to the correct route, Cadwyn will first decide on which version of the route to use based on a version parameter. Feel free to look at the example app with URL path version prefixes and arbitrary strings as versions [here](../how_to/version_with_paths_and_numbers_instead_of_headers_and_dates.md).
 
@@ -91,3 +91,21 @@ If the app has two versions: 2022-01-02 and 2022-01-05, and the request date par
 Exact match is always preferred over partial match and a request will never be matched to the higher versioned route.
 
 We implement routing like this because Cadwyn was born in a microservice architecture and it is extremely convenient to have waterfalling there. For example, imagine that you have two Cadwyn services: Payables and Receivables, each defining its own API versions. Payables service might contain 10 versions while receivables service might contain only 2 versions because it didn't need as many breaking changes. If a client requests a version that does not exist in receivables -- we will just waterfall to some earlier version, making receivables behavior consistent even if API keeps getting new versions.
+
+## API Version Parameter Title and Description
+
+You can pass a title and/or a description to `Cadwyn` constructor. They are equivalent to passing `title` and `description` to `fastapi.Path` or `fastapi.Header` constructors.
+
+```python
+app = Cadwyn(
+    ...,
+    api_version_title="My Great API version parameter",
+    api_version_description="Description of my great API version parameter",
+)
+```
+
+## API Version Context Variables
+
+Cadwyn automatically converts your data to a correct version and has "version checks" when dealing with side effects as described in [the section above](./version_changes.md#version-changes-with-side-effects). It can only do so using a special [context variable](https://docs.python.org/3/library/contextvars.html) that stores the current API version.
+
+You can also pass a different compatible contextvar to your `cadwyn.VersionBundle` constructor.

docs/concepts/api_version_parameter_and_context_variables.md

@@ -3,7 +3,7 @@
 Cadwyn uses version headers with ISO dates by default for versioning. However, you can use any strings instead of ISO dates and/or you can use path version prefixes instead of version headers. Here's our quickstart tutorial example but using version numbers and path prefixes:
 
 Feel free to mix and match the API version formats and version locations as you see fit.
-But beware that Cadwyn does not support [version waterfalling](../concepts/where_to_put_the_version_and_how_to_format_it.md#api-version-waterfalling) for arbitrary strings as versions.
+But beware that Cadwyn does not support [version waterfalling](../concepts/api_version_parameter.md#api-version-waterfalling) for arbitrary strings as versions.
 
 ```python
 {! ./docs_src/how_to/version_with_path_and_numbers_instead_of_headers_and_dates/block001.py !}

docs/how_to/version_with_paths_and_numbers_instead_of_headers_and_dates.md

@@ -119,8 +119,7 @@ nav:
       - "Endpoint migrations": "concepts/endpoint_migrations.md"
       - "Enum migrations": "concepts/enum_migrations.md"
       - "Schema migrations": "concepts/schema_migrations.md"
-      - "API Version parameter and context variables": "concepts/api_version_parameter_and_context_variables.md"
-      - "Where to put the version and how to format it": "concepts/where_to_put_the_version_and_how_to_format_it.md"
+      - "API Version parameter": "concepts/api_version_parameter.md"
       - "Changelogs": "concepts/changelogs.md"
       - "Testing": concepts/testing.md
   - "Contributing": "home/CONTRIBUTING.md"

mkdocs.yml

@@ -1,6 +1,6 @@
 [project]
 name = "cadwyn"
-version = "5.2.2"
+version = "5.3.0"
 description = "Production-ready community-driven modern Stripe-like API versioning in FastAPI"
 authors = [{ name = "Stanislav Zmiev", email = "zmievsa@gmail.com" }]
 license = "MIT"

pyproject.toml

@@ -123,9 +123,14 @@ async def get_user_addresses(user_id: uuid.UUID):
     return {"data": database_parody[f"addr_{user_id}"]}
 
 
-app = Cadwyn(versions=version_bundle, title="My amazing API")
+app = Cadwyn(
+    versions=version_bundle,
+    title="My amazing API",
+    api_version_title="My Great API version parameter",
+    api_version_description="Description of my great API version parameter",
+)
 app.generate_and_include_versioned_routers(router)
 
 
 if __name__ == "__main__":
-    uvicorn.run(app)
+    uvicorn.run(app, port=8011)