docs: 앱 내부 문서(루트 HTML, OpenAPI)에 index 엔드포인트 추가

- 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

@@ -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:
+    Returns each stock's symbol, company name, GICS Sector, and GICS Sub-Industry.
-    - Stock symbol
-    - Company name
-    - GICS Sector
-    - 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)
+    **Data Source**: Wikipedia
-    **Cache TTL**: 24 hours
+    **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:

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)"
     }
 ]