From a432fae632eb8d04182f55ab953882ef2101f624 Mon Sep 17 00:00:00 2001 From: Herculino Trotta Date: Sat, 14 Nov 2026 02:12:16 -0300 Subject: [PATCH] fix(api): clear the API docs schema warnings Describe the API token authentication, name the colliding transaction type enums, and use nullable instead of an OpenAPI 3.1 null type. A test keeps the schema free of warnings. --- app/WYGIWYH/settings.py | 5 +++++ app/apps/api/apps.py | 3 +++ app/apps/api/fields/transactions.py | 3 ++- app/apps/api/schema.py | 20 ++++++++++++++++++++ app/apps/api/tests/test_schema.py | 11 +++++++++++ 5 files changed, 41 insertions(+), 1 deletion(-) create mode 100644 app/apps/api/schema.py create mode 100644 app/apps/api/tests/test_schema.py diff --git a/app/WYGIWYH/settings.py b/app/WYGIWYH/settings.py index 9adb0d72..ff20f06a 100644 --- a/app/WYGIWYH/settings.py +++ b/app/WYGIWYH/settings.py @@ -517,6 +517,11 @@ SPECTACULAR_SETTINGS = { "DESCRIPTION": "A no-frills expense tracker", "VERSION": "1.0.0", "SERVE_INCLUDE_SCHEMA": False, + # Several models have a "type" field with different choices + "ENUM_NAME_OVERRIDES": { + "TransactionTypeEnum": "apps.transactions.models.Transaction.Type", + "TemplateTypeEnum": "apps.transactions.models.QuickTransaction.Type", + }, # OTHER SETTINGS } diff --git a/app/apps/api/apps.py b/app/apps/api/apps.py index a79077ab..05889f2a 100644 --- a/app/apps/api/apps.py +++ b/app/apps/api/apps.py @@ -4,3 +4,6 @@ from django.apps import AppConfig class ApiConfig(AppConfig): default_auto_field = "django.db.models.BigAutoField" name = "apps.api" + + def ready(self): + import apps.api.schema # noqa: F401 registers the API token scheme for the docs diff --git a/app/apps/api/fields/transactions.py b/app/apps/api/fields/transactions.py index b64ac83c..c0185f6f 100644 --- a/app/apps/api/fields/transactions.py +++ b/app/apps/api/fields/transactions.py @@ -10,7 +10,8 @@ from apps.transactions.models import ( @extend_schema_field( { - "oneOf": [{"type": "string"}, {"type": "integer"}, {"type": "null"}], + "oneOf": [{"type": "string"}, {"type": "integer"}], + "nullable": True, "description": "TransactionCategory ID or name. If the name doesn't exist, a new one will be created. Can be null if no category is assigned.", } ) diff --git a/app/apps/api/schema.py b/app/apps/api/schema.py new file mode 100644 index 00000000..499c2542 --- /dev/null +++ b/app/apps/api/schema.py @@ -0,0 +1,20 @@ +from drf_spectacular.extensions import OpenApiAuthenticationExtension + +from apps.users.models import APIToken + + +class APITokenAuthenticationScheme(OpenApiAuthenticationExtension): + """Describes APITokenAuthentication in the API docs.""" + + target_class = "apps.api.authentication.APITokenAuthentication" + name = "apiToken" + + def get_security_definition(self, auto_schema): + return { + "type": "apiKey", + "in": "header", + "name": "Authorization", + "description": ( + f"A personal API token, sent as `Token {APIToken.TOKEN_PREFIX}…`." + ), + } diff --git a/app/apps/api/tests/test_schema.py b/app/apps/api/tests/test_schema.py new file mode 100644 index 00000000..9032ff3b --- /dev/null +++ b/app/apps/api/tests/test_schema.py @@ -0,0 +1,11 @@ +import tempfile + +from django.core.management import call_command +from django.test import SimpleTestCase + + +class SchemaTests(SimpleTestCase): + def test_schema_is_valid_without_warnings(self): + """Keeps /api/docs/ complete: drf-spectacular warns when it can't describe something.""" + with tempfile.NamedTemporaryFile(suffix=".yml") as schema: + call_command("spectacular", "--validate", "--fail-on-warn", "--file", schema.name)