Skip to content

Commit 45e09b3

Browse files
SebastienMelkiclaude
SebastienMelki
and
claude
committed
docs: update documentation for new examples
- Rewrite docs/examples/README.md with all 5 examples and feature matrix - Add "More examples" section to getting-started.md - Add feature-specific example links to http-generation.md - Add validation-showcase reference to validation.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 91a6f65 commit 45e09b3

File tree

4 files changed

+136
-24
lines changed

4 files changed

+136
-24
lines changed

‎docs/examples/README.md‎

Lines changed: 112 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -2,45 +2,136 @@
22

33
> **Learn sebuf through working examples**
44
5-
## 🚀 Start here: Simple API
5+
## Quick Start: Simple API
66

77
**Want to see sebuf in action immediately?**
88

99
```bash
10-
# Clone the repo and run the complete example
1110
git clone https://github.com/SebastienMelki/sebuf.git
1211
cd sebuf/examples/simple-api
1312
make demo
1413
```
1514

16-
This starts a working HTTP API with:
17-
- User management and authentication
18-
- Multiple auth methods (email, token, social)
19-
- Type-safe request construction
20-
- OpenAPI documentation
15+
This starts a working HTTP API with user management, authentication, and OpenAPI docs.
16+
17+
**[Go to Simple API Tutorial](../../examples/simple-api/)**
18+
19+
---
20+
21+
## All Examples
22+
23+
| Example | Description | Key Features |
24+
|---------|-------------|--------------|
25+
| **[simple-api](../../examples/simple-api/)** | User authentication API | Oneof helpers, multiple auth methods, basic HTTP endpoints |
26+
| **[restful-crud](../../examples/restful-crud/)** | Product catalog API | GET, POST, PUT, PATCH, DELETE, path params, query params, pagination |
27+
| **[validation-showcase](../../examples/validation-showcase/)** | Order processing API | buf.validate patterns: string, numeric, array, map, nested validation |
28+
| **[nested-resources](../../examples/nested-resources/)** | Organization hierarchy API | Deep path nesting (3 levels), multiple path params per endpoint |
29+
| **[multi-service-api](../../examples/multi-service-api/)** | Multi-tenant platform | Multiple services, different auth levels, service/method headers |
30+
31+
---
32+
33+
## Example Details
34+
35+
### simple-api
36+
Basic introduction to sebuf with user authentication.
37+
- Oneof helpers for type-safe authentication methods
2138
- JSON and binary protobuf support
39+
- OpenAPI documentation generation
40+
41+
```bash
42+
cd examples/simple-api && make demo
43+
```
44+
45+
### restful-crud
46+
Complete RESTful CRUD operations for a product catalog.
47+
- All HTTP verbs: GET, POST, PUT, PATCH, DELETE
48+
- Path parameters: `/products/{product_id}`
49+
- Query parameters: pagination, filtering, sorting
50+
- PUT vs PATCH semantics with optional fields
51+
52+
```bash
53+
cd examples/restful-crud && make demo
54+
```
55+
56+
### validation-showcase
57+
Comprehensive buf.validate validation patterns.
58+
- String: min_len, max_len, email, uuid, pattern (regex), enum
59+
- Numeric: gte, lte, gt, lt bounds
60+
- Array: min_items, max_items, unique items
61+
- Map: max_pairs, key/value validation
62+
- Nested message validation
63+
64+
```bash
65+
cd examples/validation-showcase && make demo
66+
```
2267

23-
**→ [Go to the Simple API Tutorial](../../examples/simple-api/)**
68+
### nested-resources
69+
Complex resource hierarchies with multiple path parameters.
70+
- Organization > Team > Member/Project hierarchy
71+
- Up to 3 path parameters per endpoint
72+
- GitHub-style nested resource URLs
2473

25-
## What the example shows
74+
```bash
75+
cd examples/nested-resources && make demo
76+
```
77+
78+
**Endpoints:**
79+
```
80+
GET /api/v1/orgs/{org_id}/teams/{team_id}/members/{member_id}
81+
POST /api/v1/orgs/{org_id}/teams/{team_id}/projects
82+
```
83+
84+
### multi-service-api
85+
Multiple services with different authentication requirements.
86+
- **PublicService** - No auth required (health, info)
87+
- **UserService** - User auth (Authorization + X-Tenant-ID)
88+
- **AdminService** - Admin auth with method-specific headers
89+
90+
```bash
91+
cd examples/multi-service-api && make demo
92+
```
93+
94+
**Header patterns:**
95+
- Service-level headers applied to all methods
96+
- Method-level headers for specific operations (X-Confirm-Delete, X-Audit-Reason)
2697

27-
✅ **HTTP handlers** from protobuf services
28-
✅ **Oneof helpers** that eliminate boilerplate
29-
✅ **OpenAPI docs** that stay in sync
30-
✅ **Multiple content types** (JSON + binary protobuf)
31-
✅ **Real authentication patterns**
98+
---
99+
100+
## Running Examples
101+
102+
Each example follows the same pattern:
103+
104+
```bash
105+
# Run complete demo (generate + run)
106+
make demo
107+
108+
# Individual steps
109+
make generate # Generate code from proto
110+
make run # Start the server
111+
make test # Test with curl commands
112+
make clean # Remove generated files
113+
```
32114

33-
## More examples (coming soon)
115+
## What Each Example Demonstrates
34116

35-
- **E-commerce API** - Product catalog, cart, checkout
36-
- **Chat API** - Real-time messaging with websockets
37-
- **File Upload API** - Handle binary data and metadata
38-
- **Microservices** - Inter-service communication patterns
117+
| Feature | simple-api | restful-crud | validation | nested | multi-service |
118+
|---------|:----------:|:------------:|:----------:|:------:|:-------------:|
119+
| HTTP verbs (GET/POST) | Yes | Yes | Yes | Yes | Yes |
120+
| PUT/PATCH/DELETE | - | Yes | - | Yes | Yes |
121+
| Path parameters | - | Yes | - | Yes | Yes |
122+
| Query parameters | - | Yes | - | Yes | - |
123+
| buf.validate | Basic | Basic | Comprehensive | Basic | Basic |
124+
| Header validation | - | Yes | - | - | Yes |
125+
| Multiple services | - | - | - | - | Yes |
126+
| Nested resources | - | - | - | Yes | - |
127+
| Oneof helpers | Yes | - | - | - | - |
128+
129+
---
39130

40131
## Want to contribute an example?
41132

42-
We're looking for real-world examples that show sebuf solving actual problems. See [Contributing Guidelines](../../CONTRIBUTING.md).
133+
We welcome real-world examples that show sebuf solving actual problems. See [Contributing Guidelines](../../CONTRIBUTING.md).
43134

44135
---
45136

46-
**Start with the [Simple API Tutorial](../../examples/simple-api/) →**
137+
**Start with the [Simple API Tutorial](../../examples/simple-api/)**

‎docs/getting-started.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,17 @@ curl -X POST http://localhost:8080/api/v1/users \
172172
- **[OpenAPI Guide](./openapi-generation.md)** - Documentation customization
173173
- **[Validation Guide](./validation.md)** - Automatic request validation
174174

175+
## More examples
176+
177+
| Example | What it shows |
178+
|---------|--------------|
179+
| **[restful-crud](../examples/restful-crud/)** | All HTTP verbs, path params, query params, pagination |
180+
| **[validation-showcase](../examples/validation-showcase/)** | Comprehensive buf.validate patterns |
181+
| **[nested-resources](../examples/nested-resources/)** | Deep path nesting with multiple path params |
182+
| **[multi-service-api](../examples/multi-service-api/)** | Multiple services with different auth levels |
183+
184+
See **[All Examples](./examples/)** for the complete list.
185+
175186
## Need help?
176187

177188
- Try the [working example](../examples/simple-api/) first

‎docs/http-generation.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1419,4 +1419,9 @@ The OpenAPI spec will automatically reflect your HTTP annotations and routing.
14191419
**See also:**
14201420
- [Getting Started Guide](./getting-started.md)
14211421
- [Validation Guide](./validation.md)
1422-
- [Simple Demo](./examples/)
1422+
- [All Examples](./examples/)
1423+
1424+
**Feature-specific examples:**
1425+
- [restful-crud](../examples/restful-crud/) - All HTTP verbs, path params, query params
1426+
- [nested-resources](../examples/nested-resources/) - Deep path nesting with multiple path params
1427+
- [multi-service-api](../examples/multi-service-api/) - Service/method-level header validation

‎docs/validation.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -605,6 +605,11 @@ sebuf validation is fully compatible with the protovalidate ecosystem:
605605

606606
**Need help?**
607607
- Check the [protovalidate documentation](https://github.com/bufbuild/protovalidate) for body validation
608-
- See the [examples/simple-api](../examples/simple-api) for working examples
608+
- See the [validation-showcase example](../examples/validation-showcase/) for comprehensive validation patterns
609609
- Review [http-generation.md](./http-generation.md#header-validation) for header details
610-
- Open an issue on GitHub
610+
- Open an issue on GitHub
611+
612+
## Examples
613+
614+
- **[validation-showcase](../examples/validation-showcase/)** - Comprehensive buf.validate patterns (string, numeric, array, map, nested)
615+
- **[multi-service-api](../examples/multi-service-api/)** - Service and method-level header validation

0 commit comments

Comments
 (0)