{
  "openapi": "3.1.0",
  "info": {
    "title": "Chickenstock News API",
    "version": "1.0.0",
    "description": "국내에서 가장 빠른 한국 주식 뉴스 API. 종목별 뉴스. 모든 요청은 API 키가 필요합니다.",
    "contact": { "email": "chickenstock992@gmail.com" }
  },
  "servers": [{ "url": "https://www.chickstockfi.com/api/v1", "description": "Production" }],
  "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
  "paths": {
    "/news": {
      "get": {
        "summary": "종목별 뉴스",
        "description": "symbol로 최신 한국어 뉴스를 조회. 생략 시 전체 시장 피드.",
        "operationId": "getNews",
        "parameters": [
          { "name": "symbol", "in": "query", "schema": { "type": "string" }, "description": "종목코드(005930) 또는 미국 심볼(NVDA)" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/news/{symbol}": {
      "get": {
        "summary": "종목별 뉴스 (path)",
        "operationId": "getNewsBySymbol",
        "parameters": [
          { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/search": {
      "get": {
        "summary": "키워드/테마 뉴스 검색",
        "description": "종목이 아닌 임의 키워드(반도체·금리·AI 등)로 뉴스를 검색합니다.",
        "operationId": "searchNews",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 40 }, "description": "검색어(예: 반도체)" },
          { "name": "mode", "in": "query", "schema": { "type": "string", "enum": ["title", "all"], "default": "title" }, "description": "title=제목 정밀, all=본문 포함 광범위" },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 20 } }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/quotes/{symbol}": {
      "get": {
        "summary": "시세 + 재무",
        "description": "국내 종목 현재가·등락·52주·시가총액·PER/PBR·매출/영업이익 등.",
        "operationId": "getQuote",
        "parameters": [{ "name": "symbol", "in": "path", "required": true, "schema": { "type": "string" }, "description": "국내 6자리 코드(예: 005930)" }],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "description": "국내 6자리 코드만 지원" }
        }
      }
    },
    "/trending": {
      "get": {
        "summary": "인기/급등(이슈) 종목",
        "description": "인기 검색 + 급등 종목 랭킹과 시세.",
        "operationId": "getTrending",
        "parameters": [{ "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 10 } }],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrendingResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/disclosures": {
      "get": {
        "summary": "종목 공시",
        "operationId": "getDisclosures",
        "parameters": [
          { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" }, "description": "국내 6자리 코드" },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisclosureResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/articles/{id}/read": {
      "get": {
        "summary": "원문 열기 (리다이렉트)",
        "description": "기사 원문으로 302 리다이렉트. 인증 불필요(브라우저에서 직접 열기용).",
        "operationId": "readArticle",
        "security": [],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "302": { "description": "원문으로 리다이렉트" }, "404": { "description": "Not found" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer ck_live_…" },
      "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" }
    },
    "schemas": {
      "Article": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "art_3f9k" },
          "symbol": { "type": ["string", "null"], "example": "005930" },
          "market": { "type": "string", "enum": ["kr", "us"] },
          "title": { "type": "string" },
          "summary": { "type": ["string", "null"], "description": "기사 요약(없으면 null)" },
          "publisher": { "type": "string", "example": "연합뉴스" },
          "published_at": { "type": "string", "format": "date-time" },
          "url": { "type": "string", "format": "uri", "description": "원문 리다이렉트 링크" }
        },
        "required": ["id", "market", "title", "publisher", "published_at", "url"]
      },
      "Meta": {
        "type": "object",
        "properties": {
          "count": { "type": "integer" },
          "total": { "type": "integer", "description": "전체 매칭 수(페이지네이션)" },
          "symbol": { "type": ["string", "null"] },
          "q": { "type": "string" },
          "mode": { "type": "string" },
          "page": { "type": "integer" },
          "market": { "type": "string" },
          "as_of": { "type": "string", "format": "date-time" }
        }
      },
      "NewsResponse": {
        "type": "object",
        "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } }, "meta": { "$ref": "#/components/schemas/Meta" } }
      },
      "Quote": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string", "example": "005930" },
          "name": { "type": "string" },
          "market": { "type": "string" },
          "currency": { "type": "string" },
          "price": {
            "type": "object",
            "properties": {
              "current": { "type": "number" }, "open": { "type": "number" }, "high": { "type": "number" }, "low": { "type": "number" },
              "prev_close": { "type": "number" }, "change": { "type": "number" }, "change_rate": { "type": "number" },
              "upper_limit": { "type": "number" }, "lower_limit": { "type": "number" }
            }
          },
          "volume": { "type": "object", "properties": { "trade_value": { "type": "number" }, "shares": { "type": "number" } } },
          "range_52w": { "type": "object", "properties": { "high": { "type": "number" }, "high_date": { "type": ["string", "null"] }, "low": { "type": "number" }, "low_date": { "type": ["string", "null"] } } },
          "fundamentals": {
            "type": "object",
            "properties": {
              "market_cap": { "type": "number" }, "market_cap_rank": { "type": ["number", "null"] },
              "per": { "type": ["number", "null"] }, "pbr": { "type": ["number", "null"] }, "eps": { "type": ["number", "null"] },
              "bps": { "type": ["number", "null"] }, "dps": { "type": ["number", "null"] },
              "foreign_ratio": { "type": ["number", "null"] }, "debt_ratio": { "type": ["number", "null"] },
              "sales": { "type": ["number", "null"] }, "operating_profit": { "type": ["number", "null"] }, "net_income": { "type": ["number", "null"] },
              "listed_shares": { "type": ["number", "null"] }
            }
          },
          "sector": { "type": ["string", "null"] },
          "company_summary": { "type": ["string", "null"] },
          "market_status": { "type": ["string", "null"] },
          "as_of": { "type": "string", "format": "date-time" }
        }
      },
      "TrendingItem": {
        "type": "object",
        "properties": {
          "rank": { "type": "integer" }, "rank_change": { "type": "integer" }, "is_new": { "type": "boolean" },
          "symbol": { "type": "string" }, "name": { "type": "string" },
          "price": { "type": "number" }, "change": { "type": "string", "enum": ["RISE", "FALL", "EVEN"] }, "change_rate": { "type": "number" },
          "trade_value": { "type": "number" }, "volume": { "type": "number" }
        }
      },
      "TrendingResponse": {
        "type": "object",
        "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrendingItem" } }, "meta": { "$ref": "#/components/schemas/Meta" } }
      },
      "Disclosure": {
        "type": "object",
        "description": "DART 공식 전자공시.",
        "properties": {
          "id": { "type": "string", "description": "DART 접수번호(rcept_no)" },
          "symbol": { "type": "string" },
          "title": { "type": "string", "description": "보고서명" },
          "filer": { "type": "string", "description": "제출인", "example": "삼성전자" },
          "published_at": { "type": "string", "format": "date-time" },
          "url": { "type": "string", "format": "uri", "description": "DART 공식 뷰어 링크" }
        }
      },
      "DisclosureResponse": {
        "type": "object",
        "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Disclosure" } }, "meta": { "$ref": "#/components/schemas/Meta" } }
      },
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "docs": { "type": "string" } } } }
      }
    },
    "responses": {
      "Unauthorized": { "description": "API 키 누락/무효", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "분당/월 한도 초과", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}