{
  "openapi": "3.1.0",
  "info": {
    "title": "SAVOR Dish Recipe API",
    "description": "Search and discover recipes from SAVOR Dish, an AI-powered recipe generator with Instacart grocery delivery and meal planning. Find recipes by keyword, cuisine, dietary preference, or trending popularity. Get full recipe details with ingredients, step-by-step instructions, nutrition info, and cooking tips. Generate grocery lists and order ingredients through Instacart.",
    "version": "1.0.0",
    "contact": {
      "name": "Savor Dish",
      "url": "https://savordish.com",
      "email": "info@savordish.com"
    }
  },
  "servers": [
    {
      "url": "https://savordish.com",
      "description": "SAVOR Dish Production API"
    }
  ],
  "paths": {
    "/api/public/explore": {
      "get": {
        "operationId": "searchRecipes",
        "summary": "Search and explore recipes",
        "description": "Search recipes by keyword, filter by cuisine/category, and browse trending recipes. Returns public recipe data sorted by popularity (view count) by default.",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "description": "Search query to find recipes by title, description, cuisine, or ingredients (e.g. 'chicken pho', 'vegan pasta', 'quick dinner')",
            "schema": { "type": "string" }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter by cuisine or category (e.g. 'vietnamese', 'italian', 'mexican', 'thai', 'indian', 'japanese', 'mediterranean')",
            "schema": { "type": "string" }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sort order: 'popular' (default, by view count) or 'newest'",
            "schema": { "type": "string", "enum": ["popular", "newest"], "default": "popular" }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of recipes to return (default 20, max 50)",
            "schema": { "type": "integer", "default": 20, "maximum": 50 }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of recipes to skip for pagination",
            "schema": { "type": "integer", "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "List of matching recipes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "recipes": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/RecipeSummary" }
                    },
                    "total": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/public/recipes/{slug}": {
      "get": {
        "operationId": "getRecipeBySlug",
        "summary": "Get full recipe details",
        "description": "Retrieve complete recipe details including ingredients, step-by-step instructions, nutrition information, cooking tips, and more. Use the recipe slug from search results.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Recipe slug (e.g. 'easy-mediterranean-chickpea-salad') or recipe UUID",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Full recipe details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RecipeDetail" }
              }
            }
          },
          "404": {
            "description": "Recipe not found"
          }
        }
      }
    },
    "/api/growth/trending": {
      "get": {
        "operationId": "getTrendingRecipes",
        "summary": "Get trending recipes",
        "description": "Get currently trending and popular recipes on SAVOR Dish, ranked by trending score.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "description": "Content type to get trending items for",
            "schema": { "type": "string", "default": "recipe" }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Optional cuisine category filter",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of trending items to return",
            "schema": { "type": "integer", "default": 10, "maximum": 20 }
          }
        ],
        "responses": {
          "200": {
            "description": "List of trending recipes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/RecipeSummary" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RecipeSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string", "description": "Recipe title" },
          "slug": { "type": "string", "description": "URL-friendly slug for the recipe" },
          "description": { "type": "string", "description": "Brief description of the recipe" },
          "cuisine": { "type": "string", "description": "Cuisine type (e.g. Vietnamese, Italian)" },
          "mealType": { "type": "string", "description": "Meal type (breakfast, lunch, dinner, snack, dessert)" },
          "prepTime": { "type": "string", "description": "Preparation time (e.g. '15 minutes')" },
          "cookTime": { "type": "string", "description": "Cooking time (e.g. '30 minutes')" },
          "servings": { "type": "string", "description": "Number of servings" },
          "difficulty": { "type": "string", "description": "Difficulty level" },
          "imageUrl": { "type": "string", "description": "URL to recipe photo" },
          "url": { "type": "string", "description": "Full URL to view recipe on SAVOR Dish" }
        }
      },
      "RecipeDetail": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "slug": { "type": "string" },
          "description": { "type": "string" },
          "cuisine": { "type": "string" },
          "mealType": { "type": "string" },
          "prepTime": { "type": "string" },
          "cookTime": { "type": "string" },
          "totalTime": { "type": "string" },
          "servings": { "type": "string" },
          "difficulty": { "type": "string" },
          "ingredients": {
            "type": "array",
            "items": { "type": "string" },
            "description": "List of ingredients with quantities"
          },
          "instructions": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Step-by-step cooking instructions"
          },
          "tips": { "type": "string", "description": "Cooking tips and notes" },
          "nutritionInfo": {
            "type": "object",
            "description": "Nutritional information per serving",
            "properties": {
              "calories": { "type": "string" },
              "protein": { "type": "string" },
              "carbs": { "type": "string" },
              "fat": { "type": "string" },
              "fiber": { "type": "string" }
            }
          },
          "tags": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Recipe tags and categories"
          },
          "imageUrl": { "type": "string" },
          "url": { "type": "string", "description": "Full URL to view recipe on SAVOR Dish" }
        }
      }
    }
  }
}