0
# Operation Discovery and Analysis
1

2
Advanced operation discovery by URL, method, operationId, and comprehensive operation analysis through the Operation, Callback, and Webhook classes.
3

4
## Capabilities
5

6
### Get Operation by Path and Method
7

8
Get an Operation instance for a specific path and HTTP method.
9

10
```typescript { .api }
11
/**
12
 * Get Operation instance for a path and method
13
 * @param path - OpenAPI path (e.g., "/users/{id}")
14
 * @param method - HTTP method
15
 * @param opts - Options including webhook flag
16
 * @returns Operation or Webhook instance
17
 */
18
operation(path: string, method: HttpMethods, opts?: { isWebhook?: boolean }): Operation;
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
// Get a standard operation
25
const getUserOp = oas.operation("/users/{id}", "get");
26
console.log(getUserOp.getSummary());
27
console.log(getUserOp.getParameters());
28

29
// Get a webhook (OpenAPI 3.1)
30
const webhookOp = oas.operation("newUser", "post", { isWebhook: true });
31
if (webhookOp.isWebhook()) {
32
  console.log("This is a webhook operation");
33
}
34

35
// Handle missing operations gracefully
36
const missingOp = oas.operation("/nonexistent", "get");
37
console.log(missingOp.getSummary()); // undefined for missing operations
38
```
39

40
### Find Operation Matches by URL
41

42
Find all possible operation matches for a complete URL without specifying method.
43

44
```typescript { .api }
45
/**
46
 * Find all operation matches for a complete URL
47
 * @param url - Complete URL to match against
48
 * @returns Object mapping paths to arrays of path matches
49
 */
50
findOperationMatches(url: string): PathMatches;
51
```
52

53
**Usage Examples:**
54

55
```typescript
56
const matches = oas.findOperationMatches("https://api.example.com/users/123");
57

58
if (matches) {
59
  matches.forEach(match => {
60
    console.log(`Matched path: ${match.url.path}`);
61
    console.log(`Path parameters:`, match.url.slugs);
62
    console.log(`Original path: ${match.url.nonNormalizedPath}`);
63
  });
64
}
65
```
66

67
### Find Operation by URL and Method
68

69
Find a specific operation by complete URL and HTTP method.
70

71
```typescript { .api }
72
/**
73
 * Find operation by complete URL and method
74
 * @param url - Complete URL including origin and path
75
 * @param method - HTTP method to match
76
 * @returns Path match object or undefined if not found
77
 */
78
findOperation(url: string, method: HttpMethods): PathMatch | undefined;
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
const match = oas.findOperation("https://api.example.com/users/123", "get");
85

86
if (match) {
87
  console.log(`Found operation: ${match.url.method} ${match.url.path}`);
88
  console.log(`Parameters extracted:`, match.url.slugs); // { ":id": "123" }
89
  console.log(`Server origin: ${match.url.origin}`);
90
}
91
```
92

93
### Get Operation Instance by URL
94

95
Get an Operation instance directly from a complete URL and method.
96

97
```typescript { .api }
98
/**
99
 * Get Operation instance from complete URL and method
100
 * @param url - Complete URL to resolve
101
 * @param method - HTTP method
102
 * @returns Operation instance or undefined if not found
103
 */
104
getOperation(url: string, method: HttpMethods): Operation | undefined;
105
```
106

107
**Usage Examples:**
108

109
```typescript
110
const operation = oas.getOperation("https://api.example.com/users/123", "get");
111

112
if (operation) {
113
  console.log(`Operation ID: ${operation.getOperationId()}`);
114
  console.log(`Summary: ${operation.getSummary()}`);
115
  console.log(`Required parameters: ${operation.hasRequiredParameters()}`);
116
  
117
  // Use all Operation methods
118
  const params = operation.getParameters();
119
  const security = operation.getSecurity();
120
  const responses = operation.getResponseStatusCodes();
121
}
122
```
123

124
### Find Operation by ID
125

126
Find an operation anywhere in the API definition by its operationId.
127

128
```typescript { .api }
129
/**
130
 * Find operation by operationId
131
 * @param id - operationId to search for (exact match, case-sensitive)
132
 * @returns Operation or Webhook instance, or undefined if not found
133
 */
134
getOperationById(id: string): Operation | Webhook | undefined;
135
```
136

137
**Usage Examples:**
138

139
```typescript
140
// Find by explicit operationId
141
const getUserOp = oas.getOperationById("getUser");
142
if (getUserOp) {
143
  console.log(`Found: ${getUserOp.method.toUpperCase()} ${getUserOp.path}`);
144
}
145

146
// Find webhook by operationId
147
const webhookOp = oas.getOperationById("userCreated");
148
if (webhookOp?.isWebhook()) {
149
  console.log("Found webhook operation");
150
}
151

152
// Handle generated operationIds
153
const generatedOp = oas.getOperationById("getUsersUserId"); // Generated from GET /users/{id}
154
```
155

156
### Find Operation Without Method
157

158
Find an operation by URL without specifying the HTTP method.
159

160
```typescript { .api }
161
/**
162
 * Find operation by URL without specifying method
163
 * @param url - Complete URL to match
164
 * @returns Path match for the best matching operation
165
 */
166
findOperationWithoutMethod(url: string): PathMatch | undefined;
167
```
168

169
**Usage Examples:**
170

171
```typescript
172
const match = oas.findOperationWithoutMethod("https://api.example.com/users/123");
173

174
if (match) {
175
  // Will find the operation with the fewest path parameters
176
  console.log(`Best match: ${match.url.path}`);
177
  console.log(`Available methods:`, Object.keys(match.operation));
178
}
179
```
180

181
## Operation Class Methods
182

183
The Operation class provides comprehensive analysis capabilities:
184

185
### Basic Information
186

187
```typescript { .api }
188
interface Operation {
189
  /** Get operation summary */
190
  getSummary(): string;
191
  /** Get operation description */
192
  getDescription(): string;
193
  /** Get operation tags with metadata */
194
  getTags(): TagObject[];
195
  /** Check if operation is deprecated */
196
  isDeprecated(): boolean;
197
  /** Check if this is a webhook operation */
198
  isWebhook(): boolean;
199
}
200
```
201

202
### Operation ID Management
203

204
```typescript { .api }
205
interface Operation {
206
  /** Check if operation has an operationId */
207
  hasOperationId(): boolean;
208
  /** Get operationId or generate one from path and method */
209
  getOperationId(opts?: OperationIDGeneratorOptions): string;
210
}
211
```
212

213
**Usage Examples:**
214

215
```typescript
216
const operation = oas.operation("/users/{id}", "get");
217

218
// Basic info
219
console.log(`Summary: ${operation.getSummary()}`);
220
console.log(`Description: ${operation.getDescription()}`);
221
console.log(`Deprecated: ${operation.isDeprecated()}`);
222

223
// Tags
224
const tags = operation.getTags();
225
tags.forEach(tag => {
226
  console.log(`Tag: ${tag.name}, Description: ${tag.description || 'N/A'}`);
227
});
228

229
// Operation ID
230
if (operation.hasOperationId()) {
231
  console.log(`Operation ID: ${operation.getOperationId()}`);
232
} else {
233
  console.log(`Generated ID: ${operation.getOperationId()}`);
234
}
235
```
236

237
### Content Type Detection
238

239
```typescript { .api }
240
interface Operation {
241
  /** Get primary content type for this operation */
242
  getContentType(): string;
243
  /** Check if operation uses form URL encoding */
244
  isFormUrlEncoded(): boolean;
245
  /** Check if operation uses multipart encoding */
246
  isMultipart(): boolean;
247
  /** Check if operation uses JSON */
248
  isJson(): boolean;
249
  /** Check if operation uses XML */
250
  isXml(): boolean;
251
}
252
```
253

254
**Usage Examples:**
255

256
```typescript
257
const operation = oas.operation("/users", "post");
258

259
console.log(`Content type: ${operation.getContentType()}`);
260

261
// Type-specific handling
262
if (operation.isJson()) {
263
  console.log("Handle JSON payload");
264
} else if (operation.isFormUrlEncoded()) {
265
  console.log("Handle form data");
266
} else if (operation.isMultipart()) {
267
  console.log("Handle file uploads");
268
}
269
```
270

271
## Webhook Class
272

273
For OpenAPI 3.1 webhook operations:
274

275
```typescript { .api }
276
class Webhook extends Operation {
277
  /** OpenAPI 3.1 document reference */
278
  declare api: OAS31Document;
279
  
280
  /** Get summary with webhook-specific fallbacks */
281
  getSummary(): string;
282
  /** Get description with webhook-specific fallbacks */
283
  getDescription(): string;
284
}
285
```
286

287
## Callback Class
288

289
For callback operations within regular operations:
290

291
```typescript { .api }
292
class Callback extends Operation {
293
  /** Callback identifier */
294
  identifier: string;
295
  /** Parent path item schema */
296
  parentSchema: PathItemObject;
297
  
298
  /** Get callback identifier */
299
  getIdentifier(): string;
300
  /** Get summary with callback-specific fallbacks */
301
  getSummary(): string;
302
  /** Get description with callback-specific fallbacks */  
303
  getDescription(): string;
304
  /** Get parameters with parent parameter inheritance */
305
  getParameters(): ParameterObject[];
306
}
307
```
308

309
## Advanced Discovery Patterns
310

311
### URL Pattern Matching
312

313
The library handles complex URL patterns and server variables:
314

315
```typescript
316
// Supports server variables in discovery
317
// Server: "https://{region}.api.example.com/{version}"
318
const operation = oas.getOperation("https://us.api.example.com/v1/users/123", "get");
319

320
// Handles path parameters
321
// Path: "/users/{userId}/orders/{orderId}"
322
const match = oas.findOperation("https://api.example.com/users/123/orders/456", "get");
323
console.log(match?.url.slugs); // { ":userId": "123", ":orderId": "456" }
324
```
325

326
### Multi-Server Support
327

328
```typescript
329
// Automatically matches against all defined servers
330
const servers = [
331
  "https://api.example.com",
332
  "https://staging.example.com", 
333
  "https://{region}.example.com"
334
];
335

336
// Will match any of the above servers
337
const operation = oas.getOperation("https://staging.example.com/users/123", "get");
338
```