Document API endpoint parameters, so their descriptions and examples appear on Swagger UI

[eecavanna]

Background

Today, Swagger UI does not show descriptions or example values for the individual parameters of most of the Runtime API endpoints.

FastAPI has a feature that developers can use to cause Swagger UI to display descriptions and example values next to the input fields for parameters.

Here's a diff where I have updated an existing API endpoint's definition to take advantage of the aforementioned features:

diff --git a/nmdc_runtime/api/endpoints/nmdcschema.py b/nmdc_runtime/api/endpoints/nmdcschema.py
index 420991d..801aa4d 100644
--- a/nmdc_runtime/api/endpoints/nmdcschema.py
+++ b/nmdc_runtime/api/endpoints/nmdcschema.py
@@ -1,8 +1,9 @@
 from importlib.metadata import version
 import re
+from typing import Annotated
 
 import pymongo
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Path
 
 from nmdc_runtime.config import DATABASE_CLASS_NAME
 from nmdc_runtime.minter.config import typecodes
@@ -137,7 +138,11 @@ def get_by_id(
 
 @router.get("/nmdcschema/ids/{doc_id}/collection-name")
 def get_collection_name_by_doc_id(
-    doc_id: str,
+    doc_id: Annotated[str, Path(
+        title="Document ID",
+        description="The `id` value of the document",
+        example="nmdc:sty-11-8fb6t785",
+    )],
     mdb: MongoDatabase = Depends(get_mongo_db),
 ):
     r"""

Here is how that change affects the Swagger UI:

Before	After

Tasks

• Update all parameters of all endpoints to include descriptions
• Update some parameters of some endpoints to include example values

Footnote

I think this will facilitate both API usage and code maintenance.