From f04c7e26c046250cceacb2797801640d6260f858 Mon Sep 17 00:00:00 2001
From: rogeliolopez <rogelio.lpz94@gmail.com>
Date: Tue, 24 May 2022 19:24:59 -0500
Subject: [PATCH]  Docs for common query method

---
 examples/validators.py            |  6 +++++-
 fast_agave/blueprints/rest_api.py | 26 +++++++++++++++++++++-----
 fast_agave/version.py             |  2 +-
 3 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/examples/validators.py b/examples/validators.py
index 942491a..af743c9 100644
--- a/examples/validators.py
+++ b/examples/validators.py
@@ -3,6 +3,8 @@
 from cuenca_validations.types import QueryParams
 from pydantic import BaseModel
 import datetime as dt
+
+from pydantic.fields import Field
 from pydantic.main import BaseConfig
 
 
@@ -10,7 +12,9 @@ class AccountQuery(QueryParams):
     name: Optional[str] = None
     user_id: Optional[str] = None
     platform_id: Optional[str] = None
-    is_active: Optional[bool] = None
+    is_active: Optional[bool] = Field(
+        None, description='description for field'
+    )
 
 
 class TransactionQuery(QueryParams):
diff --git a/fast_agave/blueprints/rest_api.py b/fast_agave/blueprints/rest_api.py
index d520cf3..48582c9 100644
--- a/fast_agave/blueprints/rest_api.py
+++ b/fast_agave/blueprints/rest_api.py
@@ -8,6 +8,7 @@
 from fastapi.responses import StreamingResponse
 from mongoengine import DoesNotExist, Q
 from pydantic import ValidationError
+from pydantic.fields import Field
 from pydantic.main import BaseModel
 from starlette_context import context
 
@@ -256,9 +257,20 @@ async def retrieve(id: str, request: Request):
 
             # Build dynamically types for openapi documentation
             class QueryResponse(BaseModel):
-                items: Optional[List[response_model or Any]] = None
-                next_page_uri: Optional[str] = None
-                count: Optional[int] = None
+                items: Optional[List[response_model or Any]] = Field(
+                    None,
+                    description=f'List of {cls.__name__} that match with query filters',
+                )
+                next_page_uri: Optional[str] = Field(
+                    None, description='URL to fetch the next page of results'
+                )
+                count: Optional[int] = Field(
+                    None,
+                    description=(
+                        f'Counter of {cls.__name__} objects that match with query filters.  \n'
+                        f'Included in response only if `count` param was `true`'
+                    ),
+                )
 
             QueryResponse.__name__ = f'QueryResponse{cls.__name__}'
 
@@ -286,13 +298,17 @@ class QueryResponse(BaseModel):
                     "value": {"count": 1},
                 },
             ]
+            query_description = (
+                f'Make queries in resource {cls.__name__} and filter the result using path parameters.  \n'
+                f'The items are paginated, to iterate over them use the `next_page_uri` included in response.  \n'
+                f'If you need only a counter not the data send value `true` in `count` param.'
+            )
 
             @self.get(
                 path,
                 summary=f'Query {cls.__name__}',
                 response_model=QueryResponse,
-                description=f'Method for queries in resource {cls.__name__}. '
-                f'Filter response items using query params',
+                description=query_description,
                 responses=get_response(200, 'Successful Response', examples),
                 openapi_extra={"parameters": query_params},
             )
diff --git a/fast_agave/version.py b/fast_agave/version.py
index 2b8877c..31d8e4c 100644
--- a/fast_agave/version.py
+++ b/fast_agave/version.py
@@ -1 +1 @@
-__version__ = '0.5.0'
+__version__ = '0.6.0.dev0'