{
  "openapi": "3.0.0",
  "info": {
    "title": "GitHub Repository Discovery and Ranking API",
    "description": "API for discovering and ranking GitHub repositories based on various criteria. This API provides search functionality with customizable ranking algorithms.",
    "version": "1.0.0",
    "contact": {
      "email": "support@example.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://api.github-discovery.example.com/api/v1",
      "description": "Production server"
    },
    {
      "url": "http://localhost:3000/api/v1",
      "description": "Local development server"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JWT-based API key for authentication"
      }
    },
    "schemas": {
      "Repository": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "GitHub repository ID"
          },
          "full_name": {
            "type": "string",
            "description": "Full repository name (owner/repo)"
          },
          "owner": {
            "type": "object",
            "properties": {
              "login": {
                "type": "string",
                "description": "Repository owner username"
              }
            }
          },
          "name": {
            "type": "string",
            "description": "Repository name"
          },
          "html_url": {
            "type": "string",
            "description": "Repository URL"
          },
          "description": {
            "type": "string",
            "description": "Repository description"
          },
          "stargazers_count": {
            "type": "integer",
            "description": "Number of stars"
          },
          "forks_count": {
            "type": "integer",
            "description": "Number of forks"
          },
          "language": {
            "type": "string",
            "description": "Primary programming language"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Last update timestamp"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Creation timestamp"
          },
          "ranking_score": {
            "type": "number",
            "description": "Calculated ranking score"
          },
          "ranking_factors": {
            "type": "object",
            "properties": {
              "stars": {
                "type": "integer",
                "description": "Star count used in ranking"
              },
              "forks": {
                "type": "integer",
                "description": "Fork count used in ranking"
              },
              "activity": {
                "type": "number",
                "description": "Activity score used in ranking"
              },
              "weights": {
                "type": "object",
                "properties": {
                  "stars": {
                    "type": "number",
                    "description": "Weight applied to stars"
                  },
                  "forks": {
                    "type": "number",
                    "description": "Weight applied to forks"
                  },
                  "activity": {
                    "type": "number",
                    "description": "Weight applied to activity"
                  }
                }
              }
            }
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "query": {
            "type": "object",
            "properties": {
              "q": {
                "type": "string",
                "description": "Search query"
              },
              "lang": {
                "type": "string",
                "description": "Language filter"
              },
              "topic": {
                "type": "string",
                "description": "Topic filter"
              },
              "page": {
                "type": "integer",
                "description": "Page number"
              },
              "limit": {
                "type": "integer",
                "description": "Results per page"
              },
              "weights": {
                "type": "object",
                "properties": {
                  "stars": {
                    "type": "number"
                  },
                  "forks": {
                    "type": "number"
                  },
                  "activity": {
                    "type": "number"
                  }
                }
              }
            }
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of matching repositories"
          },
          "repositories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Repository"
            }
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Response timestamp"
          },
          "source": {
            "type": "string",
            "enum": [
              "api",
              "cache"
            ],
            "description": "Source of the response data"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error type"
          },
          "message": {
            "type": "string",
            "description": "Error message"
          },
          "details": {
            "type": "object",
            "description": "Additional error details"
          }
        }
      }
    }
  },
  "paths": {
    "/search": {
      "get": {
        "summary": "Search for GitHub repositories",
        "description": "Search for GitHub repositories with various filters and ranking options. Results are ranked based on stars, forks, and recent activity.",
        "operationId": "searchRepositories",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "description": "Filter by programming language",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "topic",
            "in": "query",
            "description": "Filter by topic",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number for pagination",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results per page",
            "schema": {
              "type": "integer",
              "default": 10,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "weights",
            "in": "query",
            "description": "Custom weights for ranking (e.g., stars:0.5,forks:0.3,activity:0.2)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with ranked repositories",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests - Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/cache/clear": {
      "post": {
        "summary": "Clear the cache",
        "description": "Clear the cache for specific search queries or all cache",
        "operationId": "clearCache",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "key": {
                    "type": "string",
                    "description": "Specific cache key to clear (optional, clears all if not provided)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cache cleared successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Health check endpoint",
        "description": "Check if the API is running",
        "operationId": "healthCheck",
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "UP"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/generateApiKey": {
      "post": {
        "summary": "Generate a new API key",
        "description": "Generate a new API key for accessing the service. The key will be sent to the registered email address.",
        "operationId": "generateApiKey",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "API key generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "apiKey": {
                      "type": "string",
                      "description": "Generated API key"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Insufficient permissions",
            "content ": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description ": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}