Enhance API metadata and tag consistency across routers for improved documentation and clarity

Author: bencap

src/mavedb/routers/access_keys.py

@@ -21,13 +21,24 @@
 from mavedb.routers.shared import ACCESS_CONTROL_ERROR_RESPONSES, PUBLIC_ERROR_RESPONSES, ROUTER_BASE_PREFIX
 from mavedb.view_models import access_key
 
+TAG_NAME = "Access Keys"
+
 router = APIRouter(
     prefix=f"{ROUTER_BASE_PREFIX}",
-    tags=["Access Keys"],
+    tags=[TAG_NAME],
     responses={**PUBLIC_ERROR_RESPONSES},
     route_class=LoggedRoute,
 )
 
+metadata = {
+    "name": TAG_NAME,
+    "description": "Manage API access keys for programmatic access to the MaveDB API.",
+    "externalDocs": {
+        "description": "Access Keys Documentation",
+        "url": "https://mavedb.org/docs/mavedb/accounts.html#api-access-tokens",
+    },
+}
+
 logger = logging.getLogger(__name__)
 
 

src/mavedb/routers/api_information.py

@@ -6,12 +6,19 @@
 from mavedb.routers.shared import PUBLIC_ERROR_RESPONSES, ROUTER_BASE_PREFIX
 from mavedb.view_models import api_version
 
+TAG_NAME = "API Information"
+
 router = APIRouter(
     prefix=f"{ROUTER_BASE_PREFIX}/api",
-    tags=["API Information"],
+    tags=[TAG_NAME],
     responses={**PUBLIC_ERROR_RESPONSES},
 )
 
+metadata = {
+    "name": TAG_NAME,
+    "description": "Retrieve information about the MaveDB API.",
+}
+
 
 @router.get("/version", status_code=200, response_model=api_version.ApiVersion, summary="Show API version")
 def show_version() -> Any:

src/mavedb/routers/collections.py

@@ -33,15 +33,22 @@
 )
 from mavedb.view_models import collection, collection_bundle
 
+TAG_NAME = "Collections"
+
 logger = logging.getLogger(__name__)
 
 router = APIRouter(
     prefix=f"{ROUTER_BASE_PREFIX}",
-    tags=["Collections"],
+    tags=[TAG_NAME],
     responses={**PUBLIC_ERROR_RESPONSES},
     route_class=LoggedRoute,
 )
 
+metadata = {
+    "name": TAG_NAME,
+    "description": "Manage the members and permissions of data set collections.",
+}
+
 
 @router.get(
     "/users/me/collections",

src/mavedb/routers/controlled_keywords.py

@@ -9,12 +9,23 @@
 from mavedb.routers.shared import PUBLIC_ERROR_RESPONSES, ROUTER_BASE_PREFIX
 from mavedb.view_models import keyword
 
+TAG_NAME = "Controlled Keywords"
+
 router = APIRouter(
     prefix=f"{ROUTER_BASE_PREFIX}/controlled-keywords",
-    tags=["Controlled Keywords"],
+    tags=[TAG_NAME],
     responses={**PUBLIC_ERROR_RESPONSES},
 )
 
+metadata = {
+    "name": TAG_NAME,
+    "description": "Retrieve controlled keywords used for annotating MaveDB records.",
+    "externalDocs": {
+        "description": "Controlled Keywords Schema",
+        "url": "https://github.com/ave-dcd/mave_vocabulary?tab=readme-ov-file",
+    },
+}
+
 
 @router.get(
     "/{key}",

src/mavedb/routers/doi_identifiers.py

@@ -10,12 +10,19 @@
 from mavedb.view_models import doi_identifier
 from mavedb.view_models.search import TextSearch
 
+TAG_NAME = "DOI Identifiers"
+
 router = APIRouter(
     prefix=f"{ROUTER_BASE_PREFIX}/doi-identifiers",
-    tags=["DOI Identifiers"],
+    tags=[TAG_NAME],
     responses={**PUBLIC_ERROR_RESPONSES},
 )
 
+metadata = {
+    "name": TAG_NAME,
+    "description": "Search and retrieve DOI identifiers associated with MaveDB records.",
+}
+
 
 @router.post(
     "/search",

src/mavedb/routers/experiment_sets.py

@@ -15,13 +15,24 @@
 from mavedb.routers.shared import ACCESS_CONTROL_ERROR_RESPONSES, PUBLIC_ERROR_RESPONSES, ROUTER_BASE_PREFIX
 from mavedb.view_models import experiment_set
 
+TAG_NAME = "Experiment Sets"
+
 router = APIRouter(
     prefix=f"{ROUTER_BASE_PREFIX}/experiment-sets",
-    tags=["Experiment Sets"],
+    tags=[TAG_NAME],
     responses={**PUBLIC_ERROR_RESPONSES},
     route_class=LoggedRoute,
 )
 
+metadata = {
+    "name": TAG_NAME,
+    "description": "Retrieve experiment sets and their associated experiments.",
+    "externalDocs": {
+        "description": "Experiment Sets Documentation",
+        "url": "https://mavedb.org/docs/mavedb/record_types.html#experiment-sets",
+    },
+}
+
 logger = logging.getLogger(__name__)
 
 

src/mavedb/routers/experiments.py

@@ -41,15 +41,26 @@
 from mavedb.view_models import experiment, score_set
 from mavedb.view_models.search import ExperimentsSearch
 
+TAG_NAME = "Experiments"
+
 logger = logging.getLogger(__name__)
 
 router = APIRouter(
     prefix=f"{ROUTER_BASE_PREFIX}",
-    tags=["Experiments"],
+    tags=[TAG_NAME],
     responses={**PUBLIC_ERROR_RESPONSES},
     route_class=LoggedRoute,
 )
 
+metadata = {
+    "name": TAG_NAME,
+    "description": "Manage and retrieve experiments and their associated data.",
+    "externalDocs": {
+        "description": "Experiments Documentation",
+        "url": "https://mavedb.org/docs/mavedb/record_types.html#experiments",
+    },
+}
+
 
 # None of any part calls this function. Feel free to modify it if we need it in the future.
 @router.get(

src/mavedb/routers/hgvs.py

@@ -10,12 +10,19 @@
 from mavedb.deps import hgvs_data_provider
 from mavedb.routers.shared import BASE_400_RESPONSE, PUBLIC_ERROR_RESPONSES, ROUTER_BASE_PREFIX
 
+TAG_NAME = "Transcripts"
+
 router = APIRouter(
     prefix=f"{ROUTER_BASE_PREFIX}/hgvs",
-    tags=["Transcripts"],
+    tags=[TAG_NAME],
     responses={**PUBLIC_ERROR_RESPONSES},
 )
 
+metadata = {
+    "name": TAG_NAME,
+    "description": "Retrieve transcript information and validate HGVS variants.",
+}
+
 
 @router.get(
     "/fetch/{accession}",

src/mavedb/routers/licenses.py

@@ -8,12 +8,23 @@
 from mavedb.routers.shared import PUBLIC_ERROR_RESPONSES, ROUTER_BASE_PREFIX
 from mavedb.view_models import license
 
+TAG_NAME = "Licenses"
+
 router = APIRouter(
     prefix=f"{ROUTER_BASE_PREFIX}/licenses",
-    tags=["Licenses"],
+    tags=[TAG_NAME],
     responses={**PUBLIC_ERROR_RESPONSES},
 )
 
+metadata = {
+    "name": TAG_NAME,
+    "description": "Retrieve information about licenses supported by MaveDB.",
+    "externalDocs": {
+        "description": "Licenses Documentation",
+        "url": "https://mavedb.org/docs/mavedb/data_licensing.html",
+    },
+}
+
 
 @router.get("/", status_code=200, response_model=List[license.ShortLicense], summary="List all licenses")
 def list_licenses(

src/mavedb/routers/log.py

@@ -6,13 +6,20 @@
 from mavedb.lib.logging.context import logging_context, save_to_logging_context
 from mavedb.routers.shared import PUBLIC_ERROR_RESPONSES, ROUTER_BASE_PREFIX
 
+TAG_NAME = "Log"
+
 router = APIRouter(
     prefix=f"{ROUTER_BASE_PREFIX}/log",
-    tags=["Log"],
+    tags=[TAG_NAME],
     responses={**PUBLIC_ERROR_RESPONSES},
     route_class=LoggedRoute,
 )
 
+metadata = {
+    "name": TAG_NAME,
+    "description": "Log interactions with the MaveDB API for auditing and debugging purposes.",
+}
+
 
 # NOTE: Despite not containing any calls to a logger, this route will log posted context
 #       by nature of its inheritance from LoggedRoute.