Add response_model to FastAPI routes for OpenAPI schema generation

- Add response_model and response_model_exclude_none to all route endpoints
- Simplify RequestAdapter by replacing openapi dict access with simple version key
- Fix Address model with explicit tags field using Field(exclude=True)
- Remove empty schemas directory
- Fix list_block_txs to return list[Union[TxUtxo, TxAccount]] instead of Txs

Author: Tommel71

gsrest/models/addresses.py

@@ -2,7 +2,7 @@
 
 from typing import Any, Optional
 
-from pydantic import ConfigDict
+from pydantic import Field
 
 from gsrest.models.base import APIModel
 from gsrest.models.common import LabeledItemRef
@@ -13,13 +13,6 @@
 class Address(APIModel):
     """Address model."""
 
-    # Allow extra fields for test fixtures that set .tags
-    model_config = ConfigDict(
-        populate_by_name=True,
-        from_attributes=True,
-        extra="allow",
-    )
-
     currency: str
     address: str
     entity: int
@@ -38,11 +31,12 @@ class Address(APIModel):
     actors: Optional[list[LabeledItemRef]] = None
     is_contract: Optional[bool] = None
     status: Optional[str] = None
+    # tags field used by test fixtures only, excluded from serialization and schema
+    tags: Optional[list[Any]] = Field(default=None, exclude=True)
 
     def to_dict(self, shallow: bool = False) -> dict[str, Any]:
-        """Override to exclude extra fields (like 'tags') from serialization."""
+        """Override to exclude test-only fields from serialization."""
         result = super().to_dict(shallow=shallow)
-        # Remove any extra fields that aren't part of the API response
         result.pop("tags", None)
         return result
 

gsrest/routes/addresses.py

@@ -5,6 +5,16 @@
 from fastapi import APIRouter, Depends, Path, Query, Request
 
 from gsrest.dependencies import ServiceContainer
+from gsrest.models import (
+    Address,
+    AddressTags,
+    AddressTxs,
+    Entity,
+    Links,
+    NeighborAddresses,
+    RelatedAddresses,
+    TagSummary,
+)
 from gsrest.routes.base import (
     RequestAdapter,
     apply_plugin_hooks,
@@ -30,6 +40,8 @@ def _normalize_page(page: Optional[str]) -> Optional[str]:
     "/addresses/{address}",
     summary="Get an address",
     operation_id="get_address",
+    response_model=Address,
+    response_model_exclude_none=True,
 )
 async def get_address(
     request: Request,
@@ -60,6 +72,8 @@ async def get_address(
     "/addresses/{address}/entity",
     summary="Get the entity of an address",
     operation_id="get_address_entity",
+    response_model=Entity,
+    response_model_exclude_none=True,
 )
 async def get_address_entity(
     request: Request,
@@ -90,6 +104,8 @@ async def get_address_entity(
     "/addresses/{address}/tag_summary",
     summary="Get attribution tag summary for a given address",
     operation_id="get_tag_summary_by_address",
+    response_model=TagSummary,
+    response_model_exclude_none=True,
 )
 async def get_tag_summary_by_address(
     request: Request,
@@ -121,6 +137,8 @@ async def get_tag_summary_by_address(
     "/addresses/{address}/tags",
     summary="Get attribution tags for a given address",
     operation_id="list_tags_by_address",
+    response_model=AddressTags,
+    response_model_exclude_none=True,
 )
 async def list_tags_by_address(
     request: Request,
@@ -160,6 +178,8 @@ async def list_tags_by_address(
     "/addresses/{address}/txs",
     summary="Get all transactions an address has been involved in",
     operation_id="list_address_txs",
+    response_model=AddressTxs,
+    response_model_exclude_none=True,
 )
 async def list_address_txs(
     request: Request,
@@ -219,6 +239,8 @@ async def list_address_txs(
     "/addresses/{address}/neighbors",
     summary="Get an address's neighbors in the address graph",
     operation_id="list_address_neighbors",
+    response_model=NeighborAddresses,
+    response_model_exclude_none=True,
 )
 async def list_address_neighbors(
     request: Request,
@@ -269,6 +291,8 @@ async def list_address_neighbors(
     "/addresses/{address}/links",
     summary="Get outgoing transactions between two addresses",
     operation_id="list_address_links",
+    response_model=Links,
+    response_model_exclude_none=True,
 )
 async def list_address_links(
     request: Request,
@@ -326,6 +350,8 @@ async def list_address_links(
     "/addresses/{address}/related_addresses",
     summary="Get related addresses to the input address",
     operation_id="list_related_addresses",
+    response_model=RelatedAddresses,
+    response_model_exclude_none=True,
 )
 async def list_related_addresses(
     request: Request,

gsrest/routes/base.py

@@ -54,14 +54,8 @@ def __getitem__(self, key):
             return self._fastapi_request.app.state.config
         elif key == "request_config":
             return {"show_private_tags": self._show_private_tags}
-        elif key == "openapi":
-            # Used by general_service for version info
-            # Try to get from generated OpenAPI schema, fall back to app version
-            schema = getattr(self._fastapi_request.app.state, "openapi_schema", None)
-            if schema:
-                return schema
-            # Fallback: construct minimal openapi info from app
-            return {"info": {"version": self._fastapi_request.app.version}}
+        elif key == "version":
+            return self._fastapi_request.app.version
         raise KeyError(key)
 
     @property

gsrest/routes/blocks.py

@@ -1,8 +1,11 @@
 """Block API routes"""
 
+from typing import Union
+
 from fastapi import APIRouter, Depends, Path, Request
 
 from gsrest.dependencies import ServiceContainer
+from gsrest.models import Block, BlockAtDate, TxAccount, TxUtxo
 from gsrest.routes.base import (
     RequestAdapter,
     apply_plugin_hooks,
@@ -19,6 +22,8 @@
     "/blocks/{height}",
     summary="Get a block by its height",
     operation_id="get_block",
+    response_model=Block,
+    response_model_exclude_none=True,
 )
 async def get_block(
     request: Request,
@@ -45,6 +50,8 @@ async def get_block(
     "/blocks/{height}/txs",
     summary="Get block transactions",
     operation_id="list_block_txs",
+    response_model=list[Union[TxUtxo, TxAccount]],
+    response_model_exclude_none=True,
 )
 async def list_block_txs(
     request: Request,
@@ -71,6 +78,8 @@ async def list_block_txs(
     "/block_by_date/{date}",
     summary="Get block by date",
     operation_id="get_block_by_date",
+    response_model=BlockAtDate,
+    response_model_exclude_none=True,
 )
 async def get_block_by_date(
     request: Request,

gsrest/routes/entities.py

@@ -5,6 +5,15 @@
 from fastapi import APIRouter, Depends, Path, Query, Request
 
 from gsrest.dependencies import ServiceContainer
+from gsrest.models import (
+    AddressTags,
+    AddressTxs,
+    Entity,
+    EntityAddresses,
+    Links,
+    NeighborEntities,
+    SearchResultLevel1,
+)
 from gsrest.routes.base import (
     RequestAdapter,
     apply_plugin_hooks,
@@ -31,6 +40,8 @@ def _normalize_page(page: Optional[str]) -> Optional[str]:
     "/entities/{entity}",
     summary="Get an entity",
     operation_id="get_entity",
+    response_model=Entity,
+    response_model_exclude_none=True,
 )
 async def get_entity(
     request: Request,
@@ -65,6 +76,8 @@ async def get_entity(
     "/entities/{entity}/addresses",
     summary="Get an entity's addresses",
     operation_id="list_entity_addresses",
+    response_model=EntityAddresses,
+    response_model_exclude_none=True,
 )
 async def list_entity_addresses(
     request: Request,
@@ -100,6 +113,8 @@ async def list_entity_addresses(
     summary="Get an entity's neighbors in the entity graph",
     operation_id="list_entity_neighbors",
     deprecated=True,
+    response_model=NeighborEntities,
+    response_model_exclude_none=True,
 )
 async def list_entity_neighbors(
     request: Request,
@@ -159,6 +174,8 @@ async def list_entity_neighbors(
     summary="Get transactions between two entities",
     operation_id="list_entity_links",
     deprecated=True,
+    response_model=Links,
+    response_model_exclude_none=True,
 )
 async def list_entity_links(
     request: Request,
@@ -217,6 +234,8 @@ async def list_entity_links(
     summary="Get address tags for a given entity",
     operation_id="list_address_tags_by_entity",
     deprecated=True,
+    response_model=AddressTags,
+    response_model_exclude_none=True,
 )
 async def list_address_tags_by_entity(
     request: Request,
@@ -252,6 +271,8 @@ async def list_address_tags_by_entity(
     summary="Get all transactions an entity has been involved in",
     operation_id="list_entity_txs",
     deprecated=True,
+    response_model=AddressTxs,
+    response_model_exclude_none=True,
 )
 async def list_entity_txs(
     request: Request,
@@ -311,6 +332,8 @@ async def list_entity_txs(
     "/entities/{entity}/search",
     summary="Search neighbors of an entity",
     operation_id="search_entity_neighbors",
+    response_model=list[SearchResultLevel1],
+    response_model_exclude_none=True,
 )
 async def search_entity_neighbors(
     request: Request,

gsrest/routes/general.py

@@ -4,6 +4,8 @@
 
 from fastapi import APIRouter, Depends, Query, Request
 
+from gsrest.dependencies import ServiceContainer
+from gsrest.models import SearchResult, Stats
 from gsrest.routes.base import (
     RequestAdapter,
     apply_plugin_hooks,
@@ -12,7 +14,6 @@
     get_tagstore_access_groups,
     to_json_response,
 )
-from gsrest.dependencies import ServiceContainer
 import gsrest.service.general_service as service
 
 router = APIRouter()
@@ -22,6 +23,8 @@
     "/stats",
     summary="Get statistics of supported currencies",
     operation_id="get_statistics",
+    response_model=Stats,
+    response_model_exclude_none=True,
 )
 async def get_statistics(
     request: Request,
@@ -44,6 +47,8 @@ async def get_statistics(
     "/search",
     summary="Returns matching addresses, transactions and labels",
     operation_id="search",
+    response_model=SearchResult,
+    response_model_exclude_none=True,
 )
 async def search(
     request: Request,

gsrest/routes/rates.py

@@ -3,6 +3,7 @@
 from fastapi import APIRouter, Depends, Path, Request
 
 from gsrest.dependencies import ServiceContainer
+from gsrest.models import Rates
 from gsrest.routes.base import (
     RequestAdapter,
     apply_plugin_hooks,
@@ -19,6 +20,8 @@
     "/rates/{height}",
     summary="Get exchange rates for a given block height",
     operation_id="get_exchange_rates",
+    response_model=Rates,
+    response_model_exclude_none=True,
 )
 async def get_exchange_rates(
     request: Request,

gsrest/routes/tags.py

@@ -6,6 +6,13 @@
 from pydantic import BaseModel
 
 from gsrest.dependencies import ServiceContainer
+from gsrest.models import (
+    Actor,
+    AddressTags,
+    Concept,
+    Taxonomy,
+    UserTagReportResponse,
+)
 from gsrest.routes.base import (
     RequestAdapter,
     apply_plugin_hooks,
@@ -41,6 +48,8 @@ class UserReportedTag(BaseModel):
     "/tags",
     summary="Get address tags by label",
     operation_id="list_address_tags",
+    response_model=AddressTags,
+    response_model_exclude_none=True,
 )
 async def list_address_tags(
     request: Request,
@@ -75,6 +84,8 @@ async def list_address_tags(
     "/tags/actors/{actor}",
     summary="Get an actor by ID",
     operation_id="get_actor",
+    response_model=Actor,
+    response_model_exclude_none=True,
 )
 async def get_actor(
     request: Request,
@@ -101,6 +112,8 @@ async def get_actor(
     "/tags/actors/{actor}/tags",
     summary="Get tags associated with an actor",
     operation_id="get_actor_tags",
+    response_model=AddressTags,
+    response_model_exclude_none=True,
 )
 async def get_actor_tags(
     request: Request,
@@ -135,6 +148,8 @@ async def get_actor_tags(
     "/tags/taxonomies",
     summary="List all taxonomies",
     operation_id="list_taxonomies",
+    response_model=list[Taxonomy],
+    response_model_exclude_none=True,
 )
 async def list_taxonomies(
     request: Request,
@@ -157,6 +172,8 @@ async def list_taxonomies(
     "/tags/taxonomies/{taxonomy}/concepts",
     summary="List concepts for a taxonomy",
     operation_id="list_concepts",
+    response_model=list[Concept],
+    response_model_exclude_none=True,
 )
 async def list_concepts(
     request: Request,
@@ -183,6 +200,8 @@ async def list_concepts(
     "/tags/report-tag",
     summary="Report a new tag",
     operation_id="report_tag",
+    response_model=UserTagReportResponse,
+    response_model_exclude_none=True,
 )
 async def report_tag(
     request: Request,

gsrest/routes/tokens.py

@@ -3,6 +3,7 @@
 from fastapi import APIRouter, Depends, Path, Request
 
 from gsrest.dependencies import ServiceContainer
+from gsrest.models import TokenConfigs
 from gsrest.routes.base import (
     RequestAdapter,
     apply_plugin_hooks,
@@ -19,6 +20,8 @@
     "/supported_tokens/",
     summary="Get supported tokens for a currency",
     operation_id="list_supported_tokens",
+    response_model=TokenConfigs,
+    response_model_exclude_none=True,
 )
 async def list_supported_tokens(
     request: Request,