Document API endpoint parameters and endpoints with descriptions and examples for Swagger UI

nmdc_runtime/api/endpoints/capabilities.py

@@ -1,7 +1,7 @@
-from typing import List
+from typing import List, Annotated
 
 import pymongo
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, Path
 
 from nmdc_runtime.api.core.util import raise404_if_none
 from nmdc_runtime.api.db.mongo import get_mongo_db
@@ -10,16 +10,41 @@
 router = APIRouter()
 
 
-@router.get("/capabilities", response_model=List[Capability])
+@router.get(
+    "/capabilities",
+    response_model=List[Capability],
+    description="List all available capabilities",
+)
 def list_capabilities(
     mdb: pymongo.database.Database = Depends(get_mongo_db),
 ):
+    """
+    Retrieve a list of all capabilities available in the system.
+
+    Capabilities define the functional requirements for workflow execution.
+    """
     return list(mdb.capabilities.find())
 
 
-@router.get("/capabilities/{capability_id}", response_model=Capability)
+@router.get(
+    "/capabilities/{capability_id}",
+    response_model=Capability,
+    description="Get details of a specific capability",
+)
 def get_capability(
-    capability_id: str,
+    capability_id: Annotated[
+        str,
+        Path(
+            title="Capability ID",
+            description="The unique identifier of the capability.",
+            examples=["cap-123"],
+        ),
+    ],
     mdb: pymongo.database.Database = Depends(get_mongo_db),
 ):
+    """
+    Retrieve detailed information about a specific capability.
+
+    Returns the capability definition including its requirements and configuration.
+    """
     return raise404_if_none(mdb.capabilities.find_one({"id": capability_id}))

nmdc_runtime/api/endpoints/ids.py

@@ -3,9 +3,9 @@
 """
 
 import re
-from typing import List, Dict, Any
+from typing import List, Dict, Any, Annotated
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Path
 from pydantic import ValidationError
 from pymongo.database import Database as MongoDatabase
 from starlette import status
@@ -33,7 +33,11 @@
 router = APIRouter()
 
 
-@router.post("/ids/mint", response_model=List[str])
+@router.post(
+    "/ids/mint",
+    response_model=List[str],
+    description="Generate new NMDC identifiers",
+)
 def mint_ids(
     mint_req: MintRequest,
     mdb: MongoDatabase = Depends(get_mongo_db),
@@ -54,12 +58,21 @@ def mint_ids(
     return ids
 
 
-@router.post("/ids/bindings", response_model=List[Dict[str, Any]])
+@router.post(
+    "/ids/bindings",
+    response_model=List[Dict[str, Any]],
+    description="Create bindings between identifiers and data objects",
+)
 def set_id_bindings(
     binding_requests: List[IdBindingRequest],
     mdb: MongoDatabase = Depends(get_mongo_db),
     site: Site = Depends(get_current_client_site),
 ):
+    """
+    Create bindings between NMDC identifiers and their associated data.
+
+    Associates identifiers with documents in the database for resolution.
+    """
     bons = [r.i for r in binding_requests]
     ids: List[IdThreeParts] = []
     for bon in bons:
@@ -119,11 +132,27 @@ def set_id_bindings(
         return [dissoc(d, "_id") for d in docs]
 
 
-@router.get("/ids/bindings/{rest:path}", response_model=Dict[str, Any])
+@router.get(
+    "/ids/bindings/{rest:path}",
+    response_model=Dict[str, Any],
+    description="Resolve an identifier to its bound data",
+)
 def get_id_bindings(
-    rest: str,
+    rest: Annotated[
+        str,
+        Path(
+            title="ID Path",
+            description="The identifier path (e.g., 'nmdc:bsm-11-abc123' or 'nmdc:bsm-11-abc123/name').",
+            examples=["nmdc:bsm-11-abc123"],
+        ),
+    ],
     mdb: MongoDatabase = Depends(get_mongo_db),
 ):
+    """
+    Resolve an NMDC identifier to its associated data.
+
+    Returns the document or field value bound to the specified identifier.
+    """
     cleaned = rest.replace("-", "")
     parts = cleaned.split(":")
     if len(parts) != 2:

nmdc_runtime/api/endpoints/jobs.py

@@ -24,7 +24,10 @@
 
 
 @router.get(
-    "/jobs", response_model=ListResponse[Job], response_model_exclude_unset=True
+    "/jobs",
+    response_model=ListResponse[Job],
+    response_model_exclude_unset=True,
+    description="List workflow jobs with optional filtering",
 )
 def list_jobs(
     req: Annotated[ListRequest, Query()],
@@ -42,20 +45,53 @@ def list_jobs(
     return list_resources(req, mdb, "jobs")
 
 
-@router.get("/jobs/{job_id}", response_model=Job, response_model_exclude_unset=True)
+@router.get(
+    "/jobs/{job_id}",
+    response_model=Job,
+    response_model_exclude_unset=True,
+    description="Get details of a specific job",
+)
 def get_job_info(
-    job_id: str,
+    job_id: Annotated[
+        str,
+        Path(
+            title="Job ID",
+            description="The unique identifier of the job.",
+            examples=["nmdc:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"],
+        ),
+    ],
     mdb: Database = Depends(get_mongo_db),
 ):
+    """
+    Retrieve detailed information about a specific job.
+
+    Returns job configuration, status, and execution metadata.
+    """
     return raise404_if_none(mdb.jobs.find_one({"id": job_id}))
 
 
-@router.post("/jobs/{job_id}:claim", response_model=Operation[ResultT, MetadataT])
+@router.post(
+    "/jobs/{job_id}:claim",
+    response_model=Operation[ResultT, MetadataT],
+    description="Claim a job for execution by a site",
+)
 def claim_job(
-    job_id: str,
+    job_id: Annotated[
+        str,
+        Path(
+            title="Job ID",
+            description="The unique identifier of the job to claim.",
+            examples=["nmdc:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"],
+        ),
+    ],
     mdb: Database = Depends(get_mongo_db),
     site: Site = Depends(get_current_client_site),
 ):
+    """
+    Claim a job for execution by the authenticated site.
+
+    Returns an operation that tracks the job execution process.
+    """
     return _claim_job(job_id, mdb, site)
 
 

nmdc_runtime/api/endpoints/object_types.py

@@ -1,7 +1,7 @@
-from typing import List
+from typing import List, Annotated
 
 import pymongo
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, Path
 
 from nmdc_runtime.api.core.util import raise404_if_none
 from nmdc_runtime.api.db.mongo import get_mongo_db
@@ -11,26 +11,67 @@
 router = APIRouter()
 
 
-@router.get("/object_types", response_model=List[ObjectType])
+@router.get(
+    "/object_types",
+    response_model=List[ObjectType],
+    description="List all available object types",
+)
 def list_object_types(
     mdb: pymongo.database.Database = Depends(get_mongo_db),
 ):
+    """
+    Retrieve a list of all object types available in the system.
+
+    Object types define the categories of data objects that can trigger workflows.
+    """
     return list(mdb.object_types.find())
 
 
-@router.get("/object_types/{object_type_id}", response_model=ObjectType)
+@router.get(
+    "/object_types/{object_type_id}",
+    response_model=ObjectType,
+    description="Get details of a specific object type",
+)
 def get_object_type(
-    object_type_id: str,
+    object_type_id: Annotated[
+        str,
+        Path(
+            title="Object Type ID",
+            description="The unique identifier of the object type.",
+            examples=["nmdc:DataObject"],
+        ),
+    ],
     mdb: pymongo.database.Database = Depends(get_mongo_db),
 ):
+    """
+    Retrieve detailed information about a specific object type.
+
+    Returns the object type definition including its properties and workflow associations.
+    """
     return raise404_if_none(mdb.object_types.find_one({"id": object_type_id}))
 
 
-@router.get("/object_types/{object_type_id}/workflows", response_model=List[Workflow])
+@router.get(
+    "/object_types/{object_type_id}/workflows",
+    response_model=List[Workflow],
+    description="List workflows triggered by an object type",
+)
 def list_object_type_workflows(
-    object_type_id: str,
+    object_type_id: Annotated[
+        str,
+        Path(
+            title="Object Type ID",
+            description="The unique identifier of the object type whose workflows to list.",
+            examples=["nmdc:DataObject"],
+        ),
+    ],
     mdb: pymongo.database.Database = Depends(get_mongo_db),
 ):
+    """
+    List all workflows that can be triggered by the specified object type.
+
+    Returns workflow definitions that are configured to execute when objects of this type are created.
+    """
     workflow_ids = [
         doc["workflow_id"]
         for doc in mdb.triggers.find({"object_type_id": object_type_id})