{
  "openapi": "3.1.0",
  "info": {
    "title": "China Working Day API",
    "description": "The only holiday API that correctly handles China's 调休 (makeup workday) system. Returns whether any date is a working day, counts working days between dates, and lists all holidays with makeup workday details.",
    "version": "1.0.0",
    "contact": {
      "name": "pinjia.day",
      "url": "https://pinjia.day/developers",
      "email": "api@pinjia.day"
    },
    "license": {
      "name": "Free tier available",
      "url": "https://pinjia.day/developers"
    }
  },
  "servers": [
    {
      "url": "https://pinjia.day",
      "description": "Production (Cloudflare Edge)"
    }
  ],
  "paths": {
    "/api/v1/isWorkday": {
      "get": {
        "operationId": "isWorkday",
        "summary": "Check if a date is a working day in China",
        "description": "Returns whether the given date is a working day, including makeup workday (调休) detection. This is the key differentiator: Feb 14, 2026 is a Saturday, but isWorkday returns true because it's a makeup workday for Spring Festival.",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "format": "date", "example": "2026-02-14" },
            "description": "Date in YYYY-MM-DD format"
          }
        ],
        "responses": {
          "200": {
            "description": "Working day status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "date": { "type": "string", "format": "date" },
                    "year": { "type": "integer" },
                    "dayOfWeek": { "type": "string" },
                    "isWorkday": { "type": "boolean" },
                    "type": { "type": "string", "enum": ["workday", "weekend", "public_holiday", "makeup_workday"] },
                    "holiday": { "type": "object", "nullable": true },
                    "makeupFor": { "type": "object", "nullable": true }
                  }
                },
                "example": {
                  "date": "2026-02-14",
                  "year": 2026,
                  "dayOfWeek": "Saturday",
                  "isWorkday": true,
                  "type": "makeup_workday",
                  "holiday": null,
                  "makeupFor": { "id": "chunjie", "name": "春节", "nameEn": "Chinese New Year (Spring Festival)" }
                }
              }
            }
          },
          "400": { "description": "Invalid date format" },
          "404": { "description": "Year not published" }
        }
      }
    },
    "/api/v1/workingDays": {
      "get": {
        "operationId": "workingDays",
        "summary": "Count working days between two dates",
        "description": "Returns the number of actual working days between two dates, correctly accounting for public holidays AND makeup workdays (调休). Essential for payroll, lead time, and deadline calculations.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "format": "date", "example": "2026-02-01" },
            "description": "Start date (YYYY-MM-DD)"
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "format": "date", "example": "2026-03-01" },
            "description": "End date (YYYY-MM-DD)"
          }
        ],
        "responses": {
          "200": {
            "description": "Working day count with breakdown",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "from": { "type": "string", "format": "date" },
                    "to": { "type": "string", "format": "date" },
                    "calendarDays": { "type": "integer" },
                    "workingDays": { "type": "integer" },
                    "publicHolidays": { "type": "integer" },
                    "weekends": { "type": "integer" },
                    "makeupWorkdays": { "type": "array" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/holidays": {
      "get": {
        "operationId": "holidays",
        "summary": "Get all holidays and makeup workdays for a year",
        "description": "Returns the complete holiday schedule for a given year, including all public holidays with date ranges and all makeup workday dates. Data sourced from State Council official notices.",
        "parameters": [
          {
            "name": "year",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "default": "2026", "example": "2026" },
            "description": "Year (default: 2026)"
          }
        ],
        "responses": {
          "200": {
            "description": "Full year holiday data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "year": { "type": "integer" },
                    "source": { "type": "string" },
                    "totalHolidayDays": { "type": "integer" },
                    "totalMakeupDays": { "type": "integer" },
                    "holidays": { "type": "array" },
                    "makeupWorkdays": { "type": "array" },
                    "publishedYears": { "type": "array" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}