clawspec_core/_tutorial/
chapter_0.rs

1//! # Chapter 0: Introduction
2//!
3//! Welcome to Clawspec! This chapter explains what Clawspec is and why you might want to use it.
4//!
5//! ## What is Clawspec?
6//!
7//! Clawspec is a Rust library that generates OpenAPI specifications from your HTTP client test code.
8//! Instead of writing OpenAPI specifications by hand or using code annotations, you write tests
9//! that exercise your API, and Clawspec captures the request/response patterns to generate
10//! accurate documentation.
11//!
12//! ## The Test-Driven Documentation Approach
13//!
14//! Traditional approaches to OpenAPI documentation have drawbacks:
15//!
16//! | Approach | Drawback |
17//! |----------|----------|
18//! | Manual YAML/JSON | Tedious, error-prone, often out of sync with actual API |
19//! | Code annotations | Clutters source code, still requires manual maintenance |
20//! | Code generation | Generated specs may not reflect actual runtime behavior |
21//!
22//! Clawspec takes a different approach: **your tests become your documentation source**.
23//!
24//! Benefits:
25//! - **Always accurate**: Documentation is generated from actual API calls
26//! - **Test coverage = doc coverage**: If it's tested, it's documented
27//! - **Type-safe**: Rust's type system ensures schema correctness
28//! - **No code clutter**: Your production code stays clean
29//!
30//! ## How It Works
31//!
32//! 1. **Write tests** that make HTTP requests to your API
33//! 2. **Use typed responses** with `#[derive(ToSchema)]` for automatic schema capture
34//! 3. **Generate OpenAPI** from the collected request/response data
35//!
36//! ```text
37//! ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
38//! │  Test Code  │ ──► │  ApiClient  │ ──► │   OpenAPI   │
39//! │             │     │  (captures) │     │    Spec     │
40//! └─────────────┘     └─────────────┘     └─────────────┘
41//! ```
42//!
43//! ## Prerequisites
44//!
45//! To follow this tutorial, you should be familiar with:
46//!
47//! - Rust basics (structs, traits, async/await)
48//! - HTTP concepts (methods, status codes, JSON)
49//! - Basic understanding of OpenAPI (helpful but not required)
50//!
51//! ## Dependencies
52//!
53//! Add these to your `Cargo.toml`:
54//!
55//! ```toml
56//! [dependencies]
57//! clawspec-core = "0.4"
58//! serde = { version = "1", features = ["derive"] }
59//! utoipa = { version = "5", features = ["preserve_order"] }
60//! tokio = { version = "1", features = ["full"] }
61//!
62//! [dev-dependencies]
63//! tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
64//! ```
65//!
66//! ## What You'll Learn
67//!
68//! By the end of this tutorial, you'll know how to:
69//!
70//! - Create and configure an API client
71//! - Make GET, POST, PUT, PATCH, and DELETE requests
72//! - Use path, query, header, and cookie parameters
73//! - Handle different response types and errors
74//! - Customize OpenAPI output with tags and descriptions
75//! - Use redaction for stable documentation examples
76//! - Integrate with test frameworks using `TestClient`
77//!
78//! Ready to start? Continue to [Chapter 1: Getting Started][super::chapter_1]!
clawspec_core/_tutorial/chapter_0.rs

clawspec_core/_tutorial/
chapter_0.rs
