Rewrite README with comprehensive documentation
- Add modern formatting with emojis and clear sections - Include detailed API reference with request/response examples - Add project structure overview - Include development, deployment, and contribution guidelines - Enhance quick start instructions with virtual environment setup - Add health check documentation and code quality tools
This commit is contained in:
Automated Action
parent
ae91c493c6
commit
974e0edf44
266
README.md
266
README.md
@ -1,72 +1,232 @@
|
||||
# Todo API
|
||||
# FastAPI Todo Application
|
||||
|
||||
A simple todo application built with FastAPI and SQLite.
|
||||
A modern, fast, and feature-rich todo management API built with FastAPI, SQLAlchemy, and SQLite.
|
||||
|
||||
## Features
|
||||
## 🚀 Quick Start
|
||||
|
||||
- Create, read, update, and delete todos
|
||||
- SQLite database with Alembic migrations
|
||||
- FastAPI with automatic API documentation
|
||||
- Health check endpoint
|
||||
- CORS enabled for all origins
|
||||
### Prerequisites
|
||||
- Python 3.8+
|
||||
- pip package manager
|
||||
|
||||
## Installation
|
||||
### Installation & Setup
|
||||
|
||||
1. Install dependencies:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
1. **Clone and navigate to the project:**
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd todoapp
|
||||
```
|
||||
|
||||
2. **Create a virtual environment (recommended):**
|
||||
```bash
|
||||
python -m venv venv
|
||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
```
|
||||
|
||||
3. **Install dependencies:**
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
4. **Initialize the database:**
|
||||
```bash
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
5. **Start the server:**
|
||||
```bash
|
||||
uvicorn main:app --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
The API will be available at `http://localhost:8000`
|
||||
|
||||
## 📋 Features
|
||||
|
||||
- ✅ **Full CRUD Operations** - Create, read, update, and delete todos
|
||||
- 🔍 **Pagination Support** - Efficient handling of large todo lists
|
||||
- 📊 **SQLite Database** - Lightweight, serverless database
|
||||
- 🔄 **Database Migrations** - Version-controlled schema changes with Alembic
|
||||
- 📚 **Auto-generated Documentation** - Interactive API docs with Swagger UI
|
||||
- 🌐 **CORS Enabled** - Cross-origin requests supported
|
||||
- 💪 **Type Safety** - Full Pydantic validation and type hints
|
||||
- 🏥 **Health Monitoring** - Built-in health check endpoint
|
||||
- 🎯 **Production Ready** - Structured codebase with best practices
|
||||
|
||||
## 🛠 Tech Stack
|
||||
|
||||
- **FastAPI** - Modern, fast web framework for building APIs
|
||||
- **SQLAlchemy** - SQL toolkit and ORM
|
||||
- **Alembic** - Database migration tool
|
||||
- **Pydantic** - Data validation using Python type annotations
|
||||
- **SQLite** - Lightweight, file-based database
|
||||
- **Uvicorn** - Lightning-fast ASGI server
|
||||
|
||||
## 📡 API Reference
|
||||
|
||||
### Base Endpoints
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/` | API information and links |
|
||||
| GET | `/health` | Health check status |
|
||||
| GET | `/docs` | Interactive API documentation |
|
||||
| GET | `/redoc` | Alternative API documentation |
|
||||
| GET | `/openapi.json` | OpenAPI specification |
|
||||
|
||||
### Todo Management
|
||||
| Method | Endpoint | Description | Request Body |
|
||||
|--------|----------|-------------|--------------|
|
||||
| POST | `/todos/` | Create a new todo | `TodoCreate` |
|
||||
| GET | `/todos/` | List all todos | Query params: `skip`, `limit` |
|
||||
| GET | `/todos/{todo_id}` | Get specific todo | - |
|
||||
| PUT | `/todos/{todo_id}` | Update todo | `TodoUpdate` |
|
||||
| DELETE | `/todos/{todo_id}` | Delete todo | - |
|
||||
|
||||
### Request/Response Models
|
||||
|
||||
#### TodoCreate
|
||||
```json
|
||||
{
|
||||
"title": "string",
|
||||
"description": "string (optional)",
|
||||
"completed": false
|
||||
}
|
||||
```
|
||||
|
||||
2. Run database migrations:
|
||||
```bash
|
||||
alembic upgrade head
|
||||
#### TodoUpdate
|
||||
```json
|
||||
{
|
||||
"title": "string (optional)",
|
||||
"description": "string (optional)",
|
||||
"completed": "boolean (optional)"
|
||||
}
|
||||
```
|
||||
|
||||
3. Start the application:
|
||||
```bash
|
||||
uvicorn main:app --host 0.0.0.0 --port 8000
|
||||
#### TodoResponse
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"title": "string",
|
||||
"description": "string",
|
||||
"completed": false,
|
||||
"created_at": "2024-01-01T00:00:00Z",
|
||||
"updated_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
## 🗂 Project Structure
|
||||
|
||||
- `GET /` - Root endpoint with API information
|
||||
- `GET /health` - Health check endpoint
|
||||
- `GET /docs` - Interactive API documentation
|
||||
- `GET /redoc` - Alternative API documentation
|
||||
- `GET /openapi.json` - OpenAPI specification
|
||||
```
|
||||
todoapp/
|
||||
├── main.py # FastAPI application entry point
|
||||
├── requirements.txt # Python dependencies
|
||||
├── alembic.ini # Alembic configuration
|
||||
├── ruff.toml # Code linting configuration
|
||||
├── app/
|
||||
│ ├── __init__.py
|
||||
│ ├── db/
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── base.py # SQLAlchemy Base class
|
||||
│ │ └── session.py # Database session configuration
|
||||
│ ├── models/
|
||||
│ │ ├── __init__.py
|
||||
│ │ └── todo.py # Todo SQLAlchemy model
|
||||
│ └── schemas/
|
||||
│ ├── __init__.py
|
||||
│ └── todo.py # Pydantic schemas
|
||||
└── alembic/
|
||||
├── env.py # Alembic environment configuration
|
||||
├── script.py.mako # Migration script template
|
||||
└── versions/ # Database migration files
|
||||
└── 001_initial_todo_table.py
|
||||
```
|
||||
|
||||
### Todo Endpoints
|
||||
## 🧪 Development
|
||||
|
||||
- `POST /todos/` - Create a new todo
|
||||
- `GET /todos/` - Get all todos (with pagination)
|
||||
- `GET /todos/{todo_id}` - Get a specific todo
|
||||
- `PUT /todos/{todo_id}` - Update a todo
|
||||
- `DELETE /todos/{todo_id}` - Delete a todo
|
||||
|
||||
## Data Model
|
||||
|
||||
Todo items have the following fields:
|
||||
- `id`: Unique identifier (auto-generated)
|
||||
- `title`: Todo title (required)
|
||||
- `description`: Optional description
|
||||
- `completed`: Boolean completion status (default: false)
|
||||
- `created_at`: Creation timestamp
|
||||
- `updated_at`: Last update timestamp
|
||||
|
||||
## Environment Variables
|
||||
|
||||
No environment variables are required for basic operation. The SQLite database is stored at `/app/storage/db/db.sqlite`.
|
||||
|
||||
## Development
|
||||
|
||||
To run with auto-reload during development:
|
||||
### Running in Development Mode
|
||||
```bash
|
||||
uvicorn main:app --reload --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
## API Documentation
|
||||
### Code Quality
|
||||
This project uses Ruff for linting and formatting:
|
||||
```bash
|
||||
ruff check .
|
||||
ruff format .
|
||||
```
|
||||
|
||||
Once the server is running, you can access:
|
||||
- Interactive documentation: http://localhost:8000/docs
|
||||
- Alternative documentation: http://localhost:8000/redoc
|
||||
- OpenAPI specification: http://localhost:8000/openapi.json
|
||||
### Database Operations
|
||||
|
||||
**Create a new migration:**
|
||||
```bash
|
||||
alembic revision --autogenerate -m "Description of changes"
|
||||
```
|
||||
|
||||
**Apply migrations:**
|
||||
```bash
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
**Rollback migrations:**
|
||||
```bash
|
||||
alembic downgrade -1
|
||||
```
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Database
|
||||
- **Type:** SQLite
|
||||
- **Location:** `/app/storage/db/db.sqlite`
|
||||
- **Connection:** Automatically created on startup
|
||||
|
||||
### Environment Variables
|
||||
No environment variables are required for basic operation. The application uses sensible defaults for development.
|
||||
|
||||
## 🏥 Health Check
|
||||
|
||||
The application includes a health check endpoint that returns the service status:
|
||||
|
||||
```bash
|
||||
curl http://localhost:8000/health
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"service": "Todo API"
|
||||
}
|
||||
```
|
||||
|
||||
## 📖 API Documentation
|
||||
|
||||
Once the server is running, access the documentation at:
|
||||
|
||||
- **Swagger UI:** http://localhost:8000/docs
|
||||
- **ReDoc:** http://localhost:8000/redoc
|
||||
- **OpenAPI JSON:** http://localhost:8000/openapi.json
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
For production deployment, consider:
|
||||
|
||||
1. **Use a production WSGI server:**
|
||||
```bash
|
||||
pip install gunicorn
|
||||
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker
|
||||
```
|
||||
|
||||
2. **Set up proper logging and monitoring**
|
||||
3. **Configure environment-specific settings**
|
||||
4. **Use a more robust database (PostgreSQL, MySQL)**
|
||||
5. **Set up SSL/TLS certificates**
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Run tests and linting
|
||||
5. Submit a pull request
|
||||
|
||||
## 📝 License
|
||||
|
||||
This project is open source and available under the MIT License.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user