{
  "openapi": "3.0.0",
  "info": {
    "title": "Nutritheous API",
    "description": "Food nutrition analysis API powered by AI vision technology. Upload food images OR provide image URLs to get detailed nutritional information including calories, macros, micronutrients, ingredients, allergens, and health insights.",
    "version": "2.0.0",
    "contact": {
      "name": "Nutritheous API Support"
    }
  },
  "servers": [
    {
      "url": "http://localhost:8080",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "BasicAuth": []
    }
  ],
  "paths": {
    "/ping": {
      "get": {
        "summary": "Health Check",
        "description": "Returns server status and current timestamp",
        "tags": ["Health"],
        "security": [],
        "responses": {
          "200": {
            "description": "Server is running",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "message": {
                      "type": "string",
                      "example": "Server is running"
                    },
                    "time": {
                      "type": "string",
                      "format": "date-time",
                      "example": "2025-10-14T20:34:41Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/analyze": {
      "post": {
        "summary": "Analyze Food Image (File Upload)",
        "description": "Upload a food image file to receive detailed nutritional analysis. Supports JPEG, PNG, WebP, GIF, BMP, and HEIC formats up to 5MB.",
        "tags": ["Analysis"],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["image"],
                "properties": {
                  "image": {
                    "type": "string",
                    "format": "binary",
                    "description": "Food image file (JPEG, PNG, WebP, GIF, BMP, HEIC). Max size: 5MB"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful analysis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NutritionResponse"
                },
                "example": {
                  "description": "Grilled chicken breast with steamed broccoli and brown rice",
                  "serving_size": "1 plate (approximately 350g)",
                  "calories": 420,
                  "protein_g": 45.5,
                  "fat_g": 8.2,
                  "saturated_fat_g": 2.1,
                  "carbohydrates_g": 38.0,
                  "fiber_g": 6.5,
                  "sugar_g": 2.3,
                  "sodium_mg": 480,
                  "cholesterol_mg": 95,
                  "ingredients": [
                    "Chicken breast",
                    "Broccoli",
                    "Brown rice",
                    "Olive oil",
                    "Garlic"
                  ],
                  "allergens": [
                    "None detected"
                  ],
                  "health_notes": "High protein, moderate carb meal. Good source of fiber and vitamins. Low in saturated fat.",
                  "confidence": 0.92
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid file format, size too large, missing image, or invalid URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalid_format": {
                    "value": {
                      "error": "Invalid image format. Supported: JPEG, PNG, WebP, GIF, BMP, HEIC"
                    }
                  },
                  "file_too_large": {
                    "value": {
                      "error": "File size exceeds 5MB limit"
                    }
                  },
                  "no_image": {
                    "value": {
                      "error": "No image provided"
                    }
                  },
                  "invalid_url": {
                    "value": {
                      "error": "Invalid image URL format"
                    }
                  },
                  "no_url": {
                    "value": {
                      "error": "No image URL provided"
                    }
                  },
                  "unsupported_image": {
                    "value": {
                      "error": "Analysis failed: OpenAI API error: You uploaded an unsupported image"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing credentials",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "401 Unauthorized - Invalid credentials"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed - Only POST is supported",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Method not allowed"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - Image processing or AI analysis failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "analysis_failed": {
                    "value": {
                      "error": "Analysis failed: OpenAI API error"
                    }
                  },
                  "conversion_failed": {
                    "value": {
                      "error": "HEIC conversion failed: sips conversion failed"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/analyze-url": {
      "post": {
        "summary": "Analyze Food Image (URL)",
        "description": "Analyze a food image from a publicly accessible URL. The image is fetched directly by OpenAI without downloading to your server - faster and more efficient for images already hosted online.",
        "tags": ["Analysis"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["image_url"],
                "properties": {
                  "image_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Publicly accessible URL of a food image (http:// or https://). Must point directly to an image file.",
                    "example": "https://example.com/food-image.jpg"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful analysis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NutritionResponse"
                },
                "example": {
                  "description": "Mixed salad bowl with grilled chicken, eggs, corn, and vegetables",
                  "serving_size": "1 bowl",
                  "calories": 450,
                  "protein_g": 30.0,
                  "fat_g": 20.0,
                  "saturated_fat_g": 4.0,
                  "carbohydrates_g": 40.0,
                  "fiber_g": 8.0,
                  "sugar_g": 6.0,
                  "sodium_mg": 600.0,
                  "cholesterol_mg": 180.0,
                  "ingredients": [
                    "grilled chicken",
                    "hard-boiled eggs",
                    "corn",
                    "edamame",
                    "cherry tomatoes",
                    "cucumbers",
                    "lettuce"
                  ],
                  "allergens": [
                    "egg",
                    "soy"
                  ],
                  "health_notes": "High protein and fiber meal with moderate healthy fats. Rich in vitamins from vegetables.",
                  "confidence": 0.85
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid or missing URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "no_url": {
                    "value": {
                      "error": "No image URL provided"
                    }
                  },
                  "invalid_url": {
                    "value": {
                      "error": "Invalid image URL format"
                    }
                  },
                  "unsupported_image": {
                    "value": {
                      "error": "Analysis failed: OpenAI API error: You uploaded an unsupported image"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing credentials",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "401 Unauthorized - Invalid credentials"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed - Only POST is supported",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Method not allowed"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - AI analysis failed or URL unreachable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "analysis_failed": {
                    "value": {
                      "error": "Analysis failed: OpenAI API error"
                    }
                  },
                  "url_unreachable": {
                    "value": {
                      "error": "Analysis failed: Could not fetch image from URL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BasicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "HTTP Basic Authentication. Username can be any value, password must match AUTH_PASSWORD environment variable."
      }
    },
    "schemas": {
      "NutritionResponse": {
        "type": "object",
        "required": [
          "description",
          "serving_size",
          "calories",
          "protein_g",
          "fat_g",
          "carbohydrates_g",
          "confidence"
        ],
        "properties": {
          "description": {
            "type": "string",
            "description": "Detailed description of the food item(s) in the image",
            "example": "Grilled chicken breast with steamed broccoli and brown rice"
          },
          "serving_size": {
            "type": "string",
            "description": "Estimated serving size (e.g., '1 plate', '2 slices', '300g')",
            "example": "1 plate (approximately 350g)"
          },
          "calories": {
            "type": "integer",
            "description": "Total estimated calories",
            "example": 420,
            "minimum": 0
          },
          "protein_g": {
            "type": "number",
            "format": "float",
            "description": "Protein in grams",
            "example": 45.5,
            "minimum": 0
          },
          "fat_g": {
            "type": "number",
            "format": "float",
            "description": "Total fat in grams",
            "example": 8.2,
            "minimum": 0
          },
          "saturated_fat_g": {
            "type": "number",
            "format": "float",
            "description": "Saturated fat in grams (optional)",
            "example": 2.1,
            "minimum": 0
          },
          "carbohydrates_g": {
            "type": "number",
            "format": "float",
            "description": "Total carbohydrates in grams",
            "example": 38.0,
            "minimum": 0
          },
          "fiber_g": {
            "type": "number",
            "format": "float",
            "description": "Dietary fiber in grams (optional)",
            "example": 6.5,
            "minimum": 0
          },
          "sugar_g": {
            "type": "number",
            "format": "float",
            "description": "Total sugars in grams (optional)",
            "example": 2.3,
            "minimum": 0
          },
          "sodium_mg": {
            "type": "number",
            "format": "float",
            "description": "Sodium in milligrams (optional)",
            "example": 480,
            "minimum": 0
          },
          "cholesterol_mg": {
            "type": "number",
            "format": "float",
            "description": "Cholesterol in milligrams (optional)",
            "example": 95,
            "minimum": 0
          },
          "ingredients": {
            "type": "array",
            "description": "List of main ingredients detected in the food",
            "items": {
              "type": "string"
            },
            "example": ["Chicken breast", "Broccoli", "Brown rice"]
          },
          "allergens": {
            "type": "array",
            "description": "List of potential allergens (dairy, nuts, gluten, etc.)",
            "items": {
              "type": "string"
            },
            "example": ["None detected"]
          },
          "health_notes": {
            "type": "string",
            "description": "Brief health insights and nutritional highlights (1-2 sentences)",
            "example": "High protein, moderate carb meal. Good source of fiber and vitamins."
          },
          "confidence": {
            "type": "number",
            "format": "float",
            "description": "AI confidence level for the analysis (0.0 to 1.0)",
            "example": 0.92,
            "minimum": 0,
            "maximum": 1
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message describing what went wrong",
            "example": "Invalid image format"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Health",
      "description": "Server health and status endpoints"
    },
    {
      "name": "Analysis",
      "description": "Food image analysis endpoints"
    }
  ]
}