Implement Scalar API docs page at /scalar

mongodb/ingest_data.py

@@ -198,7 +198,7 @@ def main():
     parser.add_argument("--db-name", default="bertron", help="MongoDB database name")
     parser.add_argument(
         "--schema-path",
-        default="https://raw.githubusercontent.com/ber-data/bertron-schema/refs/heads/main/src/schema/jsonschema/bertron_schema.json",
+        default="https://raw.githubusercontent.com/ber-data/bertron-schema/96cbe257717d44137440be369a8414d153579926/src/schema/jsonschema/bertron_schema.json",
         help="Path or URL to the BERtron schema JSON file",
     )
     parser.add_argument(

pyproject.toml

@@ -32,6 +32,11 @@ dependencies = [
   "nmdc-api-utilities>=0.3.9",
   "pydantic-settings>=2.10.1",
   "pymongo>=4.13.1",
+  # Note: We use `scalar-fastapi` to integrate Scalar API documentation with FastAPI.
+  # Note: We use a Git URL to install the `scalar-fastapi` package, because the Scalar
+  #       maintainers have not published recent versions of the package to PyPI yet.
+  # Reference: https://github.com/scalar/scalar/issues/5337#issuecomment-2781011096
+  "scalar-fastapi @ git+https://github.com/scalar/scalar/#subdirectory=integrations/fastapi",
   "uvicorn>=0.34.3",
 ]
 

src/server.py

@@ -4,6 +4,7 @@
 from fastapi import FastAPI, HTTPException, Query
 from fastapi.responses import RedirectResponse
 from pymongo import MongoClient
+from scalar_fastapi import get_scalar_api_reference
 from schema.datamodel.bertron_schema_pydantic import Entity
 import uvicorn
 
@@ -38,6 +39,19 @@
 )
 
 
+@app.get("/scalar", include_in_schema=False)
+async def get_scalar_html():
+    r"""
+    Returns the HTML markup for an interactive API docs web page powered by Scalar.
+
+    Note: This can coexist with FastAPI's built-in Swagger UI page.
+    """
+    return get_scalar_api_reference(
+        openapi_url=app.openapi_url,
+        title="BERtron API",
+    )
+
+
 @app.get("/", include_in_schema=False)
 def get_root():
     r"""Redirect to the API documentation page."""