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

[Copilot]

This PR enhances the NMDC Runtime API documentation by adding detailed parameter descriptions and examples to endpoint path parameters, as well as comprehensive endpoint documentation, making the Swagger UI much more user-friendly for developers.

Problem

Previously, API endpoint parameters in Swagger UI showed only generic descriptions like "doc_id" with no context about what values were expected or what format to use. Additionally, endpoints themselves lacked clear descriptions of their purpose and functionality. This made it difficult for developers to understand how to properly use the API endpoints.

Before:

Name: doc_id
Description: doc_id

After:

Name: doc_id
Description: The id value of the document
Example: nmdc:sty-11-8fb6t785

Solution

Parameter Documentation

Updated 28 parameters across 9 endpoint files using FastAPI's Annotated type with Path and Query parameters that include:

• Title: Human-readable parameter names
• Description: Clear explanations of parameter purpose and format
• Examples: Realistic NMDC identifier examples that developers will encounter

Endpoint Documentation

Enhanced 38 endpoints across 11 endpoint files with:

• Router descriptions: Added description parameter to @router.get(), @router.post(), etc. decorators
• Function docstrings: Added comprehensive docstrings explaining each endpoint's purpose, functionality, and behavior

Updated Endpoints

Sites Management:

• /sites/{site_id} - Site operations and credential generation
• /sites/{site_id}:putObject - Object storage operations
• /sites/{site_id}:getObjectLink - Object link generation

Workflow Operations:

• /workflows/{workflow_id} - Workflow retrieval and capabilities
• /workflows/{workflow_id}/object_types - Workflow object type listing
• /workflows/{workflow_id}/capabilities - Workflow capability listing

Data Management:

• /objects/{object_id}/* - Object operations and access management
• /object_types/{object_type_id}/* - Object type operations
• /capabilities/{capability_id} - Capability operations

Job Execution:

• /jobs/{job_id}/* - Job claiming, releasing, and status operations
• /operations/{op_id}/* - Operation tracking and updates
• /runs/{run_id}/* - Run summaries and event listing

ID Management:

• /ids/bindings/{rest:path} - Identifier resolution
• /triggers/{trigger_id} - Trigger operations

Authentication:

• Enhanced ORCiD JWT cookie parameter documentation

Example Implementation

@router.get(
    "/sites/{site_id}",
    response_model=Site,
    response_model_exclude_unset=True,
    description="Get details of a specific site by its ID",  # ← Router description
)
def get_site(
    site_id: Annotated[str, Path(
        title="Site ID",                                     # ← Parameter title
        description="The unique identifier of the site.",    # ← Parameter description
        examples=["site-123"],                               # ← Parameter example
    )],
    mdb: MongoDatabase = Depends(get_mongo_db),
):
    """
    Retrieve detailed information about a specific site.     # ← Function docstring
    
    Returns the complete site record including configuration and metadata.
    """
    return raise404_if_none(mdb.sites.find_one({"id": site_id}))

Verification

• ✅ All 28 parameters include title, description, and examples
• ✅ All 38 endpoints include router descriptions and function docstrings
• ✅ Examples follow NMDC naming conventions (nmdc:sty-11-abc123, nmdc:dobj-11-abc123)
• ✅ Zero linting errors and valid Python syntax across all files
• ✅ Parameter metadata correctly attached via Python introspection

This improvement significantly enhances the developer experience by providing contextual, actionable information directly in the Swagger UI interface and comprehensive documentation for code maintainability.

Fixes #651.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[eecavanna]

I want @copilot to also document the endpoints, themselves (e.g. by adding a docstring to each endpoint function or a description kwarg to each router decoration).

[Copilot]

I want @copilot to also document the endpoints, themselves (e.g. by adding a docstring to each endpoint function or a description kwarg to each router decoration).

I've added comprehensive endpoint documentation as requested. The changes include:

Router descriptions: Added description parameter to all @router.get(), @router.post(), etc. decorators to provide clear explanations of each endpoint's purpose in Swagger UI.

Function docstrings: Added detailed docstrings to all endpoint functions explaining their functionality, parameters, and return values.

This enhancement covers 38 endpoints across 11 files with both router-level descriptions and function-level documentation. The documentation explains the purpose of each operation, what data it returns, and any important behavioral notes.

Commit: dcd61ec

[eecavanna]

Hi @dwinston, no need to review this independently (although you can if you want); I just wanted to tell you I'm planning to pull this PR up (on screen) next time we pair, and using it as a sort of guide for a conversation. There are multiple endpoints (among these) that I'm not familiar with and I think I'd benefit from hearing you summarize them. Ultimately, I do want to document them, but documenting them in real time might make the conversation take longer than we have.

[eecavanna]

I forgot to mention: all commits on this branch were made by GitHub Copilot (i.e., AI). I haven't reviewed most of the changes, myself, yet (I started to while out for a walk, but only got through 2-3 files).