Update README with comprehensive project documentation
- Add detailed project overview and features - Include installation and setup instructions - Document API endpoints and structure - Add development guidelines and information - Improve project documentation for users and contributors
This commit is contained in:
Automated Action
parent
b3cbb43878
commit
90c2213853
212
README.md
212
README.md
@ -1,3 +1,211 @@
|
||||
# FastAPI Application
|
||||
# Weather Dashboard API
|
||||
|
||||
This is a FastAPI application bootstrapped by BackendIM, the AI-powered backend generation platform.
|
||||
A powerful API for retrieving weather data, forecasts, and managing location bookmarks, built with FastAPI and SQLite.
|
||||
|
||||
## Features
|
||||
|
||||
- **User Authentication**: Secure JWT-based authentication
|
||||
- **Current Weather Data**: Get real-time weather information for any location
|
||||
- **Weather Forecasts**: Access 5-day weather forecasts
|
||||
- **Location Bookmarking**: Save and manage your favorite locations
|
||||
- **Default Location**: Set a default location for quick weather checks
|
||||
- **Caching**: Efficient caching to minimize external API calls
|
||||
- **OpenAPI Documentation**: Auto-generated, interactive API documentation
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Framework**: FastAPI
|
||||
- **Database**: SQLite with SQLAlchemy ORM
|
||||
- **Migrations**: Alembic
|
||||
- **Authentication**: JWT with OAuth2
|
||||
- **Password Hashing**: Bcrypt
|
||||
- **HTTP Client**: HTTPX
|
||||
- **External API**: OpenWeatherMap API
|
||||
- **Documentation**: Swagger UI / ReDoc
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.8+
|
||||
- OpenWeatherMap API key (free tier available)
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Create a `.env` file in the root directory with the following variables:
|
||||
|
||||
```
|
||||
OPENWEATHER_API_KEY=your_api_key_here
|
||||
SECRET_KEY=your_secret_key_here
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
1. Clone the repository:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/weather-dashboard-api.git
|
||||
cd weather-dashboard-api
|
||||
```
|
||||
|
||||
2. Install dependencies:
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
3. Set up the database:
|
||||
|
||||
```bash
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
## Running the Application
|
||||
|
||||
Start the development server:
|
||||
|
||||
```bash
|
||||
uvicorn main:app --reload
|
||||
```
|
||||
|
||||
The API will be available at http://localhost:8000
|
||||
|
||||
## API Documentation
|
||||
|
||||
Interactive API documentation is available at:
|
||||
|
||||
- Swagger UI: http://localhost:8000/docs
|
||||
- ReDoc: http://localhost:8000/redoc
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Authentication
|
||||
|
||||
- `POST /api/v1/users/register` - Register a new user
|
||||
- `POST /api/v1/users/login` - Login and get access token
|
||||
- `GET /api/v1/users/me` - Get current user information
|
||||
|
||||
### Weather Data
|
||||
|
||||
- `GET /api/v1/weather/current` - Get current weather for specific coordinates
|
||||
- `GET /api/v1/weather/current/default` - Get current weather for default location
|
||||
- `GET /api/v1/weather/forecast` - Get 5-day forecast for specific coordinates
|
||||
- `GET /api/v1/weather/forecast/default` - Get 5-day forecast for default location
|
||||
|
||||
### Location Management
|
||||
|
||||
- `GET /api/v1/locations` - Get all saved locations
|
||||
- `GET /api/v1/locations/default` - Get default location
|
||||
- `POST /api/v1/locations` - Create a new location
|
||||
- `GET /api/v1/locations/{location_id}` - Get a specific location
|
||||
- `PUT /api/v1/locations/{location_id}` - Update a specific location
|
||||
- `DELETE /api/v1/locations/{location_id}` - Delete a specific location
|
||||
|
||||
### Health Check
|
||||
|
||||
- `GET /health` - Check API health status
|
||||
|
||||
## Database Models
|
||||
|
||||
### User
|
||||
|
||||
- ID
|
||||
- Email (unique)
|
||||
- Username (unique)
|
||||
- Hashed Password
|
||||
- Is Active
|
||||
- Is Superuser
|
||||
- Created At
|
||||
- Updated At
|
||||
- Relationships: Locations
|
||||
|
||||
### Location
|
||||
|
||||
- ID
|
||||
- Name
|
||||
- Latitude
|
||||
- Longitude
|
||||
- Country (optional)
|
||||
- Is Default
|
||||
- Created At
|
||||
- Updated At
|
||||
- User ID (foreign key)
|
||||
- Relationships: User
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
weather-dashboard-api/
|
||||
├── alembic.ini # Alembic configuration
|
||||
├── main.py # FastAPI application entry point
|
||||
├── requirements.txt # Python dependencies
|
||||
├── app/ # Application package
|
||||
│ ├── api/ # API endpoints
|
||||
│ │ ├── deps.py # API dependencies
|
||||
│ │ └── v1/ # API version 1
|
||||
│ │ ├── endpoints/ # API route handlers
|
||||
│ │ └── router.py # API router
|
||||
│ ├── core/ # Core functionality
|
||||
│ │ ├── config.py # App configuration
|
||||
│ │ └── security.py # Security utilities
|
||||
│ ├── crud/ # CRUD operations
|
||||
│ ├── db/ # Database setup
|
||||
│ │ └── session.py # DB session
|
||||
│ ├── models/ # SQLAlchemy models
|
||||
│ ├── schemas/ # Pydantic schemas
|
||||
│ └── services/ # Business logic services
|
||||
│ ├── cache_service.py # Caching service
|
||||
│ └── weather_service.py # Weather API client
|
||||
└── migrations/ # Alembic migrations
|
||||
├── env.py # Migration environment
|
||||
├── script.py.mako # Migration template
|
||||
└── versions/ # Migration scripts
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
The API includes comprehensive error handling:
|
||||
|
||||
- Invalid input validation
|
||||
- Authentication and authorization errors
|
||||
- Resource not found errors
|
||||
- External API communication errors
|
||||
- Rate limiting and caching errors
|
||||
|
||||
## Caching Strategy
|
||||
|
||||
The API implements a simple in-memory caching strategy to minimize calls to the OpenWeatherMap API:
|
||||
|
||||
- Cache duration is configurable (default: 5 minutes)
|
||||
- Separate cache keys for current weather and forecasts
|
||||
- Automatic cache invalidation on expiration
|
||||
|
||||
## Development
|
||||
|
||||
To contribute to this project:
|
||||
|
||||
1. Create a feature branch:
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
2. Make your changes and run tests:
|
||||
```bash
|
||||
pytest
|
||||
```
|
||||
|
||||
3. Run code linting:
|
||||
```bash
|
||||
ruff check --fix
|
||||
```
|
||||
|
||||
4. Submit a pull request
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the LICENSE file for details.
|
||||
|
||||
## Acknowledgements
|
||||
|
||||
- [FastAPI](https://fastapi.tiangolo.com/)
|
||||
- [SQLAlchemy](https://www.sqlalchemy.org/)
|
||||
- [Alembic](https://alembic.sqlalchemy.org/)
|
||||
- [OpenWeatherMap API](https://openweathermap.org/api)
|
||||
Loading…
x
Reference in New Issue
Block a user