Skip to content

Commit a0b6bac

Browse files
TuntiiTuntii
committed
Add Learning & Examples section to cookbook
Introduces a new 'Learning & Examples' section with structured learning paths and links to a comprehensive examples repository. Updates SUMMARY.md and introduction.md to reference the new section, providing clearer guidance for new users and hands-on learners.
1 parent 2e54c88 commit a0b6bac

File tree

3 files changed

+261
-0
lines changed

3 files changed

+261
-0
lines changed

‎docs/cookbook/src/SUMMARY.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,4 +39,6 @@
3939
- [HTTP/3 (QUIC)](recipes/http3_quic.md)
4040
- [Automatic Status Page](recipes/status_page.md)
4141

42+
- [Part V: Learning & Examples](learning/README.md)
43+
4244

‎docs/cookbook/src/introduction.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,22 @@ This is not just API documentation. This is a collection of:
1010
- **Keynotes**: High-level architectural decisions and "why" we made them.
1111
- **Patterns**: The repeated structures (like `Action` and `Service`) that form the backbone of our code.
1212
- **Recipes**: Practical, step-by-step guides for adding features, testing, and maintaining cleanliness.
13+
- **Learning Paths**: Structured progressions with real-world examples.
14+
15+
## 🚀 New: Examples Repository
16+
17+
Looking for hands-on learning? Check out our **[Examples Repository](https://github.com/Tuntii/rustapi-rs-examples)** with 18 complete projects:
18+
19+
| Category | Examples |
20+
|----------|----------|
21+
| **Getting Started** | hello-world, crud-api |
22+
| **Authentication** | auth-api (JWT), rate-limit-demo |
23+
| **Database** | sqlx-crud, event-sourcing |
24+
| **AI/LLM** | toon-api, mcp-server |
25+
| **Real-time** | websocket, graphql-api |
26+
| **Production** | microservices, serverless-lambda |
27+
28+
👉 See [Learning & Examples](learning/README.md) for structured learning paths.
1329

1430
## Visual Identity
1531
This cookbook is styled with the **RustAPI Premium Dark** theme, focusing on readability, contrast, and modern "glassmorphism" aesthetics.
@@ -18,3 +34,5 @@ This cookbook is styled with the **RustAPI Premium Dark** theme, focusing on rea
1834
- Want to add a feature? Jump to [Adding a New Feature](recipes/new_feature.md).
1935
- Want to understand performance? Read [Performance Philosophy](architecture/performance.md).
2036
- Need to check code quality? See [Maintenance](recipes/maintenance.md).
37+
- **New to RustAPI?** Follow our [Learning Paths](learning/README.md).
38+

‎docs/cookbook/src/learning/README.md‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
# Learning & Examples
2+
3+
Welcome to the RustAPI learning resources! This section provides structured learning paths and links to comprehensive real-world examples to help you master the framework.
4+
5+
## 📚 Learning Resources
6+
7+
### Official Examples Repository
8+
9+
We maintain a comprehensive examples repository with **18 real-world projects** demonstrating RustAPI's full capabilities:
10+
11+
🔗 **[rustapi-rs-examples](https://github.com/Tuntii/rustapi-rs-examples)** - Complete examples from hello-world to production microservices
12+
13+
### Why Use the Examples Repository?
14+
15+
| Benefit | Description |
16+
|---------|-------------|
17+
| **Structured Learning** | Progress from beginner → intermediate → advanced |
18+
| **Real-world Patterns** | Production-ready implementations you can adapt |
19+
| **Feature Discovery** | Find examples by the features you want to learn |
20+
| **AI-Friendly** | Module-level docs help AI assistants understand your code |
21+
22+
---
23+
24+
## 🎯 Learning Paths
25+
26+
Choose a learning path based on your goals:
27+
28+
### 🚀 Path 1: REST API Developer
29+
30+
Build production-ready REST APIs with RustAPI.
31+
32+
| Step | Example | Skills Learned |
33+
|------|---------|----------------|
34+
| 1 | `hello-world` | Basic routing, handlers, server setup |
35+
| 2 | `crud-api` | CRUD operations, extractors, error handling |
36+
| 3 | `auth-api` | JWT authentication, protected routes |
37+
| 4 | `middleware-chain` | Custom middleware, logging, CORS |
38+
| 5 | `sqlx-crud` | Database integration, async queries |
39+
40+
**Related Cookbook Recipes:**
41+
- [Creating Resources](../recipes/crud_resource.md)
42+
- [JWT Authentication](../recipes/jwt_auth.md)
43+
- [Database Integration](../recipes/db_integration.md)
44+
45+
---
46+
47+
### 🏗️ Path 2: Microservices Architect
48+
49+
Design and build distributed systems with RustAPI.
50+
51+
| Step | Example | Skills Learned |
52+
|------|---------|----------------|
53+
| 1 | `crud-api` | Service fundamentals |
54+
| 2 | `middleware-chain` | Cross-cutting concerns |
55+
| 3 | `rate-limit-demo` | API protection, throttling |
56+
| 4 | `microservices` | Service communication patterns |
57+
| 5 | `microservices-advanced` | Service discovery, Consul integration |
58+
59+
**Related Cookbook Recipes:**
60+
- [Custom Middleware](../recipes/custom_middleware.md)
61+
- [Production Tuning](../recipes/high_performance.md)
62+
- [Deployment](../recipes/deployment.md)
63+
64+
---
65+
66+
### ⚡ Path 3: Real-time Applications
67+
68+
Build interactive, real-time features with WebSockets.
69+
70+
| Step | Example | Skills Learned |
71+
|------|---------|----------------|
72+
| 1 | `hello-world` | Framework basics |
73+
| 2 | `websocket` | WebSocket connections, message handling |
74+
| 3 | `middleware-chain` | Connection middleware |
75+
| 4 | `graphql-api` | Subscriptions, real-time queries |
76+
77+
**Related Cookbook Recipes:**
78+
- [Real-time Chat](../recipes/websockets.md)
79+
- [Handlers & Extractors](../concepts/handlers.md)
80+
81+
---
82+
83+
### 🤖 Path 4: AI/LLM Integration
84+
85+
Build AI-friendly APIs with TOON format and MCP support.
86+
87+
| Step | Example | Skills Learned |
88+
|------|---------|----------------|
89+
| 1 | `crud-api` | API fundamentals |
90+
| 2 | `toon-api` | TOON format for LLM-friendly responses |
91+
| 3 | `mcp-server` | Model Context Protocol implementation |
92+
| 4 | `proof-of-concept` | Combining multiple AI features |
93+
94+
**Related Cookbook Recipes:**
95+
- [rustapi-toon: The Diplomat](../crates/rustapi_toon.md)
96+
97+
---
98+
99+
## 📦 Examples by Category
100+
101+
### Getting Started
102+
| Example | Description | Difficulty |
103+
|---------|-------------|------------|
104+
| `hello-world` | Minimal RustAPI server | ⭐ Beginner |
105+
| `crud-api` | Complete CRUD operations | ⭐ Beginner |
106+
107+
### Authentication & Security
108+
| Example | Description | Difficulty |
109+
|---------|-------------|------------|
110+
| `auth-api` | JWT authentication flow | ⭐⭐ Intermediate |
111+
| `middleware-chain` | Middleware composition | ⭐⭐ Intermediate |
112+
| `rate-limit-demo` | API rate limiting | ⭐⭐ Intermediate |
113+
114+
### Database Integration
115+
| Example | Description | Difficulty |
116+
|---------|-------------|------------|
117+
| `sqlx-crud` | SQLx with PostgreSQL/SQLite | ⭐⭐ Intermediate |
118+
| `event-sourcing` | Event sourcing patterns | ⭐⭐⭐ Advanced |
119+
120+
### AI & LLM
121+
| Example | Description | Difficulty |
122+
|---------|-------------|------------|
123+
| `toon-api` | TOON format responses | ⭐⭐ Intermediate |
124+
| `mcp-server` | Model Context Protocol | ⭐⭐⭐ Advanced |
125+
126+
### Real-time & GraphQL
127+
| Example | Description | Difficulty |
128+
|---------|-------------|------------|
129+
| `websocket` | WebSocket chat example | ⭐⭐ Intermediate |
130+
| `graphql-api` | GraphQL with async-graphql | ⭐⭐⭐ Advanced |
131+
132+
### Production Patterns
133+
| Example | Description | Difficulty |
134+
|---------|-------------|------------|
135+
| `microservices` | Basic service communication | ⭐⭐⭐ Advanced |
136+
| `microservices-advanced` | Consul service discovery | ⭐⭐⭐ Advanced |
137+
| `serverless-lambda` | AWS Lambda deployment | ⭐⭐⭐ Advanced |
138+
139+
---
140+
141+
## 🔧 Feature Matrix
142+
143+
Find examples by the RustAPI features they demonstrate:
144+
145+
| Feature | Examples |
146+
|---------|----------|
147+
| `#[get]`, `#[post]` macros | All examples |
148+
| `State<T>` extractor | `crud-api`, `auth-api`, `sqlx-crud` |
149+
| `Json<T>` extractor | `crud-api`, `auth-api`, `graphql-api` |
150+
| `ValidatedJson<T>` | `auth-api`, `crud-api` |
151+
| JWT (`jwt` feature) | `auth-api`, `microservices` |
152+
| CORS (`cors` feature) | `middleware-chain`, `auth-api` |
153+
| Rate Limiting | `rate-limit-demo`, `auth-api` |
154+
| WebSockets (`ws` feature) | `websocket`, `graphql-api` |
155+
| TOON (`toon` feature) | `toon-api`, `mcp-server` |
156+
| OpenAPI/Swagger | All examples |
157+
158+
---
159+
160+
## 🚦 Getting Started with Examples
161+
162+
### Clone the Repository
163+
164+
```bash
165+
git clone https://github.com/Tuntii/rustapi-rs-examples.git
166+
cd rustapi-rs-examples
167+
```
168+
169+
### Run an Example
170+
171+
```bash
172+
cd hello-world
173+
cargo run
174+
```
175+
176+
### Test an Example
177+
178+
```bash
179+
# Most examples have tests
180+
cargo test
181+
182+
# Or use the TestClient
183+
cd ../crud-api
184+
cargo test
185+
```
186+
187+
### Explore the Structure
188+
189+
Each example includes:
190+
- `README.md` - Detailed documentation with API endpoints
191+
- `src/main.rs` - Entry point with server setup
192+
- `src/handlers.rs` - Request handlers (where applicable)
193+
- `Cargo.toml` - Dependencies and feature flags
194+
- Tests demonstrating the TestClient
195+
196+
---
197+
198+
## 📖 Cross-Reference: Cookbook ↔ Examples
199+
200+
| Cookbook Recipe | Related Examples |
201+
|-----------------|------------------|
202+
| [Creating Resources](../recipes/crud_resource.md) | `crud-api`, `sqlx-crud` |
203+
| [JWT Authentication](../recipes/jwt_auth.md) | `auth-api` |
204+
| [CSRF Protection](../recipes/csrf_protection.md) | `auth-api`, `middleware-chain` |
205+
| [Database Integration](../recipes/db_integration.md) | `sqlx-crud`, `event-sourcing` |
206+
| [File Uploads](../recipes/file_uploads.md) | `file-upload` (coming soon) |
207+
| [Custom Middleware](../recipes/custom_middleware.md) | `middleware-chain` |
208+
| [Real-time Chat](../recipes/websockets.md) | `websocket` |
209+
| [Production Tuning](../recipes/high_performance.md) | `microservices-advanced` |
210+
| [Deployment](../recipes/deployment.md) | `serverless-lambda` |
211+
212+
---
213+
214+
## 💡 Contributing Examples
215+
216+
Have a great example to share? We welcome contributions!
217+
218+
1. Fork the [rustapi-rs-examples](https://github.com/Tuntii/rustapi-rs-examples) repository
219+
2. Create your example following our structure guidelines
220+
3. Add comprehensive documentation in README.md
221+
4. Submit a pull request
222+
223+
### Example Guidelines
224+
225+
- Include a clear README with prerequisites and API endpoints
226+
- Add code comments explaining RustAPI-specific patterns
227+
- Include working tests using `rustapi-testing`
228+
- List the feature flags used
229+
230+
---
231+
232+
## 🔗 Additional Resources
233+
234+
- **[RustAPI GitHub](https://github.com/Tuntii/RustAPI)** - Framework source code
235+
- **[API Reference](https://docs.rs/rustapi-rs)** - Generated documentation
236+
- **[Feature Flags Reference](../reference/)** - All available features
237+
- **[Architecture Guide](../architecture/system_overview.md)** - How RustAPI works internally
238+
239+
---
240+
241+
> 💬 **Need help?** Open an issue in the examples repository or join our community discussions!

0 commit comments

Comments
 (0)