From af88f89f69c75ea310ad42dd8858ffe07bb36bcc Mon Sep 17 00:00:00 2001
From: I Luk Kim <yirugi@gmail.com>
Date: Sat, 14 Mar 2026 20:52:38 -0700
Subject: [PATCH] =?UTF-8?q?docs:=20=EC=95=B1=20=EB=82=B4=EB=B6=80=20?=
 =?UTF-8?q?=EB=AC=B8=EC=84=9C(=EB=A3=A8=ED=8A=B8=20HTML,=20OpenAPI)?=
 =?UTF-8?q?=EC=97=90=20index=20=EC=97=94=EB=93=9C=ED=8F=AC=EC=9D=B8?=
 =?UTF-8?q?=ED=8A=B8=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- main.py 루트 HTML: Stock Market Data 섹션에 /stocks/index/{index_name} 항목 및 예시 추가
- stocks 태그 설명 업데이트 (index constituents 포함)
- get_index_constituents: summary/response_description/docstring 상세화

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/api/v1/endpoints/stocks.py | 27 +++++++++++++++++----------
 app/main.py                    | 15 +++++++++++++++
 2 files changed, 32 insertions(+), 10 deletions(-)

diff --git a/app/api/v1/endpoints/stocks.py b/app/api/v1/endpoints/stocks.py
index 5b6ef81..b372a80 100644
--- a/app/api/v1/endpoints/stocks.py
+++ b/app/api/v1/endpoints/stocks.py
@@ -18,7 +18,11 @@ router = APIRouter()
 logger = logging.getLogger("app.api.v1.stocks")
 
 
-@router.get("/index/{index_name}")
+@router.get(
+    "/index/{index_name}",
+    summary="Get index constituents (S&P 500 / Nasdaq 100)",
+    response_description="List of constituent stocks with symbol, name, sector, and industry",
+)
 @with_cache(namespace="stocks:index", ttl=86400, key_params=["index_name"])
 async def get_index_constituents(
     index_name: str,
@@ -26,18 +30,21 @@ async def get_index_constituents(
     force_refresh: bool = Query(False, description="If true, bypasses cache and fetches fresh data"),
 ):
     """
-    Get index constituents from Wikipedia
+    Get current constituents of a major stock index from Wikipedia.
 
-    Returns current constituents of the specified stock index:
-    - Stock symbol
-    - Company name
-    - GICS Sector
-    - GICS Sub-Industry
+    Returns each stock's symbol, company name, GICS Sector, and GICS Sub-Industry.
 
-    **Supported indexes**: `sp500`, `nasdaq100`
+    **Supported values for `index_name`**:
+    - `sp500` — S&P 500 (~503 stocks)
+    - `nasdaq100` — Nasdaq 100 (~101 stocks)
 
-    **Data Source**: Wikipedia (List of S&P 500 companies / Nasdaq-100)
-    **Cache TTL**: 24 hours
+    **Data Source**: Wikipedia
+    **Cache TTL**: 24 hours (`X-Cache: HIT/MISS`, `ETag` headers included)
+    **Timeout**: 30 seconds (Wikipedia fetch)
+
+    **Error codes**:
+    - `400` — unsupported `index_name`
+    - `504` — Wikipedia response timed out
     """
     supported = list(index_constituents_service.INDEXES.keys())
     if index_name not in supported:
diff --git a/app/main.py b/app/main.py
index 922f29b..a356070 100644
--- a/app/main.py
+++ b/app/main.py
@@ -148,6 +148,7 @@ async def root_documentation():
                 <li><code>GET /stocks/trending</code> - Trending stocks with intelligent parameter coordination (n=500 default)</li>
                 <li><code>GET /stocks/most-active</code> - Most actively traded stocks</li>
                 <li><code>GET /stocks/52-week-gainers</code> - Top 52-week gaining stocks</li>
+                <li><code>GET /stocks/index/{{index_name}}</code> - S&P 500 / Nasdaq 100 constituents from Wikipedia (24h cache) — <code>sp500</code> | <code>nasdaq100</code></li>
             </ul>
 
             <h3>FRED Economic Data <span class="new-badge">NEW</span></h3>
@@ -226,6 +227,16 @@ curl "http://localhost:18001/api/v1/stocks/trending"
 # Custom total count
 curl "http://localhost:18001/api/v1/stocks/trending?n=200"</code></pre>
 
+            <h3>Index Constituents <span class="new-badge">NEW</span></h3>
+            <pre><code># S&P 500 constituents (~503 stocks, cached 24h)
+curl "http://localhost:18001/api/v1/stocks/index/sp500"
+
+# Nasdaq 100 constituents (~101 stocks, cached 24h)
+curl "http://localhost:18001/api/v1/stocks/index/nasdaq100"
+
+# Force refresh (bypass cache)
+curl "http://localhost:18001/api/v1/stocks/index/sp500?force_refresh=true"</code></pre>
+
             <h3>FRED Economic Data <span class="new-badge">NEW</span></h3>
             <pre><code># Get GDP series information
 curl "http://localhost:18001/api/v1/fred/proxy/series?series_id=GDP"
@@ -450,6 +461,10 @@ app.openapi_tags = [
     {
         "name": "screener",
         "description": "Stock screener — condition-based filtering by market cap, volume, price, P/E, sector, exchange"
+    },
+    {
+        "name": "stocks",
+        "description": "Stock market data — most active, 52-week gainers, trending, and index constituents (S&P 500 / Nasdaq 100)"
     }
 ]