1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
use ;
use OperationMetadata;
use CollectorSender;
use ExpectedStatusCodes;
use SecurityRequirement;
use ;
pub const BODY_MAX_LENGTH: usize = 1024;
/// Builder for configuring HTTP API calls with comprehensive parameter and validation support.
///
/// `ApiCall` provides a fluent interface for building HTTP requests with automatic OpenAPI schema collection.
/// It supports query parameters, headers, request bodies, and flexible status code validation.
///
/// # Method Groups
///
/// ## Request Body Methods
/// - [`json(data)`](Self::json) - Set JSON request body
/// - [`form(data)`](Self::form) - Set form-encoded request body
/// - [`multipart(form)`](Self::multipart) - Set multipart form request body
/// - [`text(content)`](Self::text) - Set plain text request body
/// - [`raw(bytes)`](Self::raw) - Set raw binary request body
///
/// ## Parameter Methods
/// - [`with_query(query)`](Self::with_query) - Set query parameters
/// - [`with_headers(headers)`](Self::with_headers) - Set request headers
/// - [`with_header(name, value)`](Self::with_header) - Add single header
///
/// ## Status Code Validation
/// - [`with_expected_status_codes(codes)`](Self::with_expected_status_codes) - Set expected status codes
/// - [`with_status_range_inclusive(range)`](Self::with_status_range_inclusive) - Set inclusive range (200..=299)
/// - [`with_status_range(range)`](Self::with_status_range) - Set exclusive range (200..300)
/// - [`add_expected_status(code)`](Self::add_expected_status) - Add single expected status
/// - [`add_expected_status_range_inclusive(range)`](Self::add_expected_status_range_inclusive) - Add inclusive range
/// - [`add_expected_status_range(range)`](Self::add_expected_status_range) - Add exclusive range
/// - [`with_client_errors()`](Self::with_client_errors) - Accept 2xx and 4xx codes
///
/// ## OpenAPI Metadata
/// - [`with_operation_id(id)`](Self::with_operation_id) - Set operation ID
/// - [`with_tags(tags)`](Self::with_tags) - Set operation tags (or use automatic tagging)
/// - [`with_description(desc)`](Self::with_description) - Set operation description (or use automatic description)
///
/// ## Response Descriptions (requires `redaction` feature)
/// - [`with_response_description(desc)`](Self::with_response_description) - Set description for the actual returned status code
///
/// ## Execution
/// - `.await` - Execute the request and return response (⚠️ **must consume result for OpenAPI**)
///
/// # Default Behavior
///
/// - **Status codes**: Accepts 200-499 (inclusive of 200, exclusive of 500)
/// - **Content-Type**: Automatically set based on body type
/// - **Schema collection**: Request/response schemas are automatically captured
/// - **Operation metadata**: Automatically generated if not explicitly set
///
/// ## Automatic OpenAPI Metadata Generation
///
/// When you don't explicitly set operation metadata, `ApiCall` automatically generates:
///
/// ### **Automatic Tags**
/// Tags are extracted from the request path using intelligent parsing:
///
/// ```text
/// Path: /api/v1/users/{id} → Tags: ["users"]
/// Path: /users → Tags: ["users"]
/// Path: /users/export → Tags: ["users", "export"]
/// Path: /observations/import → Tags: ["observations", "import"]
/// ```
///
/// **Path Prefix Skipping**: Common API prefixes are automatically skipped:
/// - `api`, `v1`, `v2`, `v3`, `rest`, `service` (and more)
/// - `/api/v1/users` becomes `["users"]`, not `["api", "v1", "users"]`
///
/// **Special Action Detection**: Certain path segments get their own tags:
/// - `import`, `upload`, `export`, `search`, `bulk`
/// - `/users/export` → `["users", "export"]`
///
/// ### **Automatic Descriptions**
/// Descriptions are generated based on HTTP method and path:
///
/// ```text
/// GET /users → "Retrieve users"
/// GET /users/{id} → "Retrieve user by ID"
/// POST /users → "Create user"
/// PUT /users/{id} → "Update user by ID"
/// DELETE /users/{id} → "Delete user by ID"
/// ```
///
/// ### **Automatic Operation IDs**
/// Generated from HTTP method and path: `"get-users-id"`, `"post-users"`, etc.
///
/// You can override any of these by calling the corresponding `with_*` methods.