{
  "openapi": "3.1.0",
  "info": {
    "title": "LouVue Restaurant Inspection API",
    "version": "1.0.0",
    "description": "Public, read-only API for Louisville, KY restaurant health-inspection data. No authentication required. Data sourced from Louisville Metro Public Health & Wellness.",
    "contact": {
      "name": "LouVue",
      "url": "https://louvue.com"
    },
    "license": {
      "name": "Open Data",
      "url": "https://louvue.com/docs/api"
    }
  },
  "servers": [
    { "url": "https://louvue.com/api/v1", "description": "Production" }
  ],
  "paths": {
    "/restaurants": {
      "get": {
        "summary": "Search restaurants",
        "description": "Returns a paginated list of restaurants, optionally filtered by search query, grade, and city. Each result includes the most recent inspection grade.",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Matches name, address, city, or ZIP (case-insensitive substring)." },
          { "name": "grade", "in": "query", "schema": { "type": "string", "example": "A,B" }, "description": "Comma-separated grades to include: A, B, C, or P." },
          { "name": "city", "in": "query", "schema": { "type": "string" }, "description": "Exact city name." },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
          { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["name-asc","name-desc","date-asc","date-desc","grade-asc","grade-desc","score-asc","score-desc"], "default": "name-asc" } }
        ],
        "responses": {
          "200": {
            "description": "Paginated restaurants",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RestaurantPage" }
              }
            }
          }
        }
      }
    },
    "/restaurants/{id}": {
      "get": {
        "summary": "Get restaurant detail",
        "description": "Returns full establishment record, recent inspection summary, final grade, complete inspection history, and all recorded violations.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": {
            "description": "Restaurant detail",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RestaurantDetail" }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/stats": {
      "get": {
        "summary": "City-wide inspection stats",
        "responses": {
          "200": {
            "description": "Aggregate counts",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Stats" }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Health check",
        "responses": {
          "200": {
            "description": "Service is up",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "service": { "type": "string", "example": "louvue-api" },
                    "version": { "type": "string", "example": "1.0.0" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string" } }
      },
      "RecentInspection": {
        "type": "object",
        "properties": {
          "establishment_id": { "type": "integer" },
          "score_recent": { "type": ["integer", "null"] },
          "grade_recent": { "type": "string" },
          "date_recent": { "type": "string", "format": "date" },
          "score_2": { "type": ["integer", "null"] },
          "grade_2": { "type": "string" },
          "date_2": { "type": "string" },
          "score_3": { "type": ["integer", "null"] },
          "grade_3": { "type": "string" },
          "date_3": { "type": "string" }
        }
      },
      "FinalGrade": {
        "type": "object",
        "properties": {
          "establishment_id": { "type": "integer" },
          "final_grade": { "type": "string" },
          "final_score": { "type": ["integer", "null"] },
          "final_inspection_date": { "type": "string", "format": "date" },
          "final_grade_type": { "type": "string", "enum": ["REGULAR","FOLLOWUP","COMPLAINT"] },
          "is_follow_up_after_c": { "type": "boolean" },
          "has_consecutive_c_grades": { "type": "boolean" }
        }
      },
      "Restaurant": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "permit_number": { "type": ["integer", "null"] },
          "name": { "type": "string" },
          "address": { "type": "string" },
          "city": { "type": "string" },
          "state": { "type": "string" },
          "zip": { "type": "string" },
          "latitude": { "type": ["number", "null"] },
          "longitude": { "type": ["number", "null"] },
          "type_description": { "type": "string" },
          "subtype_description": { "type": "string" },
          "google_place_id": { "type": ["string", "null"] },
          "recent": { "$ref": "#/components/schemas/RecentInspection", "nullable": true },
          "finalGrade": { "$ref": "#/components/schemas/FinalGrade", "nullable": true }
        }
      },
      "RestaurantPage": {
        "type": "object",
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Restaurant" } },
          "total": { "type": "integer" },
          "page": { "type": "integer" },
          "pageSize": { "type": "integer" },
          "totalPages": { "type": "integer" }
        }
      },
      "Inspection": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "establishment_id": { "type": "integer" },
          "inspection_date": { "type": "string", "format": "date" },
          "score": { "type": ["integer", "null"] },
          "grade": { "type": "string" }
        },
        "additionalProperties": true
      },
      "Violation": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "establishment_id": { "type": "integer" },
          "inspection_date": { "type": "string", "format": "date" },
          "description": { "type": "string" },
          "critical": { "type": "boolean" }
        },
        "additionalProperties": true
      },
      "RestaurantDetail": {
        "allOf": [
          { "$ref": "#/components/schemas/Restaurant" },
          {
            "type": "object",
            "properties": {
              "inspections": { "type": "array", "items": { "$ref": "#/components/schemas/Inspection" } },
              "violations": { "type": "array", "items": { "$ref": "#/components/schemas/Violation" } }
            }
          }
        ]
      },
      "Stats": {
        "type": "object",
        "properties": {
          "totalRestaurants": { "type": "integer" },
          "totalInspections": { "type": "integer" },
          "gradeACount": { "type": "integer" },
          "gradeBCount": { "type": "integer" },
          "gradeCCount": { "type": "integer" }
        }
      }
    }
  }
}