openapi: 3.0.3
info:
  title: The社史 API
  version: "1.0.0"
  description: |
    日本の上場企業の歴史・財務・沿革・役員・大株主データを JSON で公開する静的 API。
    認証不要。`{stock_code}` は東証証券コード（例: 1332 = 日本水産）。

    ## ⚠️ 安定性に関する注意

    本 API のレスポンス構造（フィールド名・ネスト・型）は **予告なく頻繁に破壊的変更されます**。
    LLM / AI Agent が **その都度 JSON 構造を解釈して柔軟に利用する前提** で設計されており、
    キー名や階層を固定でハードコードしたクライアント実装には向きません。

    安定したスキーマを必要とする利用ケースには適さないため、
    そのような用途では生 JSON を直接消費せず、LLM 経由の構造解釈レイヤを挟んでください。
servers:
  - url: https://the-shashi.com
paths:
  /companies.json:
    get:
      summary: 全社一覧
      description: 公開している全社のメタ情報リスト
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object

  /api/{stock_code}/history.json:
    get:
      summary: 歴史概略
      parameters:
        - $ref: "#/components/parameters/StockCode"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object

  /api/{stock_code}/data.json:
    get:
      summary: 財務データ（PL / BS / CF / セグメント）
      parameters:
        - $ref: "#/components/parameters/StockCode"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object

  /api/{stock_code}/timeline.json:
    get:
      summary: 沿革（年表）
      parameters:
        - $ref: "#/components/parameters/StockCode"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object

  /api/{stock_code}/executive.json:
    get:
      summary: 役員・歴代経営者
      parameters:
        - $ref: "#/components/parameters/StockCode"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object

  /api/{stock_code}/shareholder.json:
    get:
      summary: 大株主
      parameters:
        - $ref: "#/components/parameters/StockCode"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object

components:
  parameters:
    StockCode:
      name: stock_code
      in: path
      required: true
      description: 東証証券コード（4桁数字または英数字、例 1332、130A）
      schema:
        type: string
        example: "1332"
