openapi: 3.0.3
info:
  title: Seireki API (元号くん)
  description: |
    Japanese calendar conversion API that provides Western (Gregorian) and Japanese (Wareki) calendar information,
    along with Japanese holiday data and zodiac (Eto) information.
  version: 1.0.0
  contact:
    name: Yuki Matsukura
    url: https://seireki.teraren.com
servers:
  - url: https://seireki.teraren.com
    description: Production server
  - url: http://localhost:3000
    description: Local development server

paths:
  /:
    get:
      summary: Get current date information
      description: Returns current date in both Western and Japanese calendars, including zodiac information
      tags:
        - Home
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum: [json]
          required: false
          description: Response format (use 'json' for JSON response)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrentDateInfo'
              example:
                wareki: "令和8年"
                seireki: 2026
                eto: "午年"
                date: "2026年1月21日"

  /healthcheck.json:
    get:
      summary: Health check endpoint
      description: Returns server status with current timestamp
      tags:
        - System
      responses:
        '200':
          description: Server is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthCheck'
              example:
                timestamp: 1737435600

  /seireki.json:
    get:
      summary: List Western calendar years
      description: Returns a list of Western calendar years from 1900 to 2050 with their corresponding Japanese calendar years
      tags:
        - Western Calendar
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/YearListItem'
              example:
                - seireki: "2026年"
                  wareki: "令和8年"
                  url: "https://seireki.teraren.com/seireki/2026.json"
                - seireki: "2025年"
                  wareki: "令和7年"
                  url: "https://seireki.teraren.com/seireki/2025.json"

  /seireki/{year}.json:
    get:
      summary: Get Western calendar year details
      description: Returns detailed information for a specific Western calendar year
      tags:
        - Western Calendar
      parameters:
        - name: year
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 3000
          description: Western calendar year (1-3000)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YearDetail'
              example:
                seireki: "2026年"
                wareki: "令和8年"
                eto: "午年"
                age: 0
                url: "https://seireki.teraren.com/seireki/2026.json"
        '404':
          description: Year out of supported range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "西暦1年から西暦3000年までをサポートしています。"

  /wareki.json:
    get:
      summary: List Japanese calendar years
      description: Returns a list of Japanese calendar years from 1900 to 2050 with their corresponding Western calendar years
      tags:
        - Japanese Calendar
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/YearListItem'
              example:
                - seireki: "2026年"
                  wareki: "令和8年"
                  url: "https://seireki.teraren.com/wareki/2026.json"
                - seireki: "2025年"
                  wareki: "令和7年"
                  url: "https://seireki.teraren.com/wareki/2025.json"

  /wareki/{year}.json:
    get:
      summary: Get Japanese calendar year details
      description: Returns detailed information for a specific Japanese calendar year (by Western year number)
      tags:
        - Japanese Calendar
      parameters:
        - name: year
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 3000
          description: Western calendar year (1-3000, must have valid Japanese calendar representation)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YearDetail'
              example:
                seireki: "2026年"
                wareki: "令和8年"
                eto: "午年"
                age: 0
                url: "https://seireki.teraren.com/wareki/2026.json"
        '404':
          description: Year out of supported range or Japanese calendar does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "和暦が存在しません。"

  /holiday.json:
    get:
      summary: List years with holiday information
      description: Returns a list of years with available holiday data (current year + 3 years down to 1970)
      tags:
        - Holidays
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HolidayYearListItem'
              example:
                - seireki: "2026年"
                  wareki: "令和8年"
                  url: "https://seireki.teraren.com/holiday/2026.json"
                  number_of_holidays: 16
                - seireki: "2025年"
                  wareki: "令和7年"
                  url: "https://seireki.teraren.com/holiday/2025.json"
                  number_of_holidays: 16

  /holiday/{year}.json:
    get:
      summary: Get holidays for a specific year
      description: Returns all Japanese holidays for the specified year
      tags:
        - Holidays
      parameters:
        - name: year
          in: path
          required: true
          schema:
            type: integer
            minimum: 1970
          description: Western calendar year (1970 or later)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Holiday'
              example:
                - date: "2026-01-01"
                  name: "元日"
                - date: "2026-01-12"
                  name: "成人の日"
                - date: "2026-02-11"
                  name: "建国記念の日"
        '404':
          description: Year not supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "西暦1970年以降をサポートしています。"

  /holiday/google:
    get:
      summary: Export holidays in Google Calendar format
      description: Returns holidays in iCalendar format compatible with Google Calendar
      tags:
        - Holidays
      responses:
        '200':
          description: Successful response
          content:
            text/calendar:
              schema:
                type: string
                format: binary

components:
  schemas:
    CurrentDateInfo:
      type: object
      properties:
        wareki:
          type: string
          description: Current date in Japanese calendar (Wareki)
          example: "令和8年"
        seireki:
          type: integer
          description: Current year in Western calendar
          example: 2026
        eto:
          type: string
          description: Chinese zodiac for the current year
          example: "午年"
        date:
          type: string
          description: Localized date string in Japanese
          example: "2026年1月21日"
      required:
        - wareki
        - seireki
        - eto
        - date

    HealthCheck:
      type: object
      properties:
        timestamp:
          type: integer
          description: Current server timestamp (Unix time)
          example: 1737435600
      required:
        - timestamp

    YearListItem:
      type: object
      properties:
        seireki:
          type: string
          description: Year in Western calendar with Japanese text
          example: "2026年"
        wareki:
          type: string
          description: Year in Japanese calendar with Japanese text
          example: "令和8年"
        url:
          type: string
          format: uri
          description: URL to get detailed information for this year
          example: "https://seireki.teraren.com/seireki/2026.json"
      required:
        - seireki
        - wareki
        - url

    YearDetail:
      type: object
      properties:
        seireki:
          type: string
          description: Year in Western calendar with Japanese text
          example: "2026年"
        wareki:
          type: string
          description: Year in Japanese calendar with Japanese text (may include alternative era name if year spans multiple eras)
          example: "令和8年"
        eto:
          type: string
          description: Chinese zodiac for the year
          example: "午年"
        age:
          type: integer
          description: Age of person born in January of that year
          example: 0
        url:
          type: string
          format: uri
          description: URL to this resource
          example: "https://seireki.teraren.com/seireki/2026.json"
      required:
        - seireki
        - wareki
        - eto
        - age
        - url

    HolidayYearListItem:
      type: object
      properties:
        seireki:
          type: string
          description: Year in Western calendar with Japanese text
          example: "2026年"
        wareki:
          type: string
          description: Year in Japanese calendar with Japanese text
          example: "令和8年"
        url:
          type: string
          format: uri
          description: URL to get holidays for this year
          example: "https://seireki.teraren.com/holiday/2026.json"
        number_of_holidays:
          type: integer
          description: Total number of holidays in this year
          example: 16
      required:
        - seireki
        - wareki
        - url
        - number_of_holidays

    Holiday:
      type: object
      properties:
        date:
          type: string
          format: date
          description: Holiday date in ISO 8601 format
          example: "2026-01-01"
        name:
          type: string
          description: Name of the holiday in Japanese
          example: "元日"
      required:
        - date
        - name

    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message in Japanese
          example: "西暦1年から西暦3000年までをサポートしています。"

tags:
  - name: Home
    description: Homepage and current date information
  - name: System
    description: System health check endpoints
  - name: Western Calendar
    description: Western (Gregorian) calendar conversion endpoints
  - name: Japanese Calendar
    description: Japanese (Wareki) calendar conversion endpoints
  - name: Holidays
    description: Japanese national holidays information