0
# Operations and Paths
1

2
The operations and paths system defines API endpoints with their HTTP operations, parameters, request bodies, and responses. This includes path definitions, operation specifications, parameter handling, and content type management for complete API endpoint documentation.
3

4
## Capabilities
5

6
### Path Definition
7

8
Represents an API endpoint path with its operations and shared parameters.
9

10
```python { .api }
11
@dataclass
12
class Path:
13
    url: str
14
    summary: Optional[str] = None
15
    description: Optional[str] = None
16
    operations: list[Operation] = field(default_factory=list)
17
    parameters: list[Parameter] = field(default_factory=list)
18
    extensions: Optional[dict] = field(default_factory=dict)
19
```
20

21
**Properties:**
22
- `url`: Path template string (e.g., "/users/{id}")
23
- `summary`: Brief summary of the path
24
- `description`: Detailed description of the path
25
- `operations`: List of HTTP operations for this path
26
- `parameters`: Path-level parameters shared by all operations
27
- `extensions`: Custom path extensions (x-* properties)
28

29
### Operation Definition
30

31
Represents an HTTP operation (GET, POST, etc.) with its complete specification.
32

33
```python { .api }
34
@dataclass
35
class Operation:
36
    method: OperationMethod
37
    responses: list[Response]
38
    summary: Optional[str] = None
39
    description: Optional[str] = None
40
    operation_id: Optional[str] = None
41
    external_docs: Optional[ExternalDoc] = None
42
    request_body: Optional[RequestBody] = None
43
    deprecated: Optional[bool] = field(default=False)
44
    parameters: list[Parameter] = field(default_factory=list)
45
    tags: list[str] = field(default_factory=list)
46
    security: list[dict[str, Any]] = field(default_factory=list)
47
    extensions: Optional[dict] = field(default_factory=dict)
48
```
49

50
**Properties:**
51
- `method`: HTTP method from OperationMethod enum
52
- `responses`: List of possible responses
53
- `summary`: Brief operation summary
54
- `description`: Detailed operation description
55
- `operation_id`: Unique identifier for the operation
56
- `external_docs`: Link to external documentation
57
- `request_body`: Request body specification
58
- `deprecated`: Whether the operation is deprecated
59
- `parameters`: Operation-specific parameters
60
- `tags`: Tags for grouping/categorization
61
- `security`: Security requirements for this operation
62
- `extensions`: Custom operation extensions
63

64
### Parameter Definition
65

66
Defines input parameters for operations including query, path, header, and cookie parameters.
67

68
```python { .api }
69
@dataclass
70
class Parameter:
71
    name: str
72
    location: ParameterLocation
73
    schema: Optional[Schema] = None
74
    content: Optional[list[Content]] = None
75
    required: Optional[bool] = field(default=False)
76
    description: Optional[str] = None
77
    deprecated: Optional[bool] = field(default=False)
78
    style: Optional[str] = None
79
    explode: Optional[bool] = field(default=False)
80
    extensions: Optional[dict] = field(default_factory=dict)
81
```
82

83
**Properties:**
84
- `name`: Parameter name
85
- `location`: Parameter location (header, query, path, cookie)
86
- `schema`: Parameter schema definition
87
- `content`: Alternative content-based parameter definition
88
- `required`: Whether the parameter is required
89
- `description`: Parameter description
90
- `deprecated`: Whether the parameter is deprecated
91
- `style`: Serialization style for the parameter
92
- `explode`: Whether to explode array/object parameters
93
- `extensions`: Custom parameter extensions
94

95
### Request Body
96

97
Defines the request body content and requirements for operations.
98

99
```python { .api }  
100
@dataclass
101
class RequestBody:
102
    content: list[Content]
103
    description: Optional[str] = None
104
    required: Optional[bool] = field(default=False)
105
```
106

107
**Properties:**
108
- `content`: List of supported content types and schemas
109
- `description`: Request body description
110
- `required`: Whether the request body is required
111

112
### Response Definition
113

114
Defines operation responses including status codes, content, and headers.
115

116
```python { .api }
117
@dataclass
118
class Response:
119
    is_default: bool
120
    description: str
121
    code: Optional[int] = None
122
    content: Optional[list[Content]] = None
123
    headers: list[Header] = field(default_factory=list)
124
```
125

126
**Properties:**
127
- `is_default`: Whether this is the default response
128
- `description`: Response description (required)
129
- `code`: HTTP status code (None for default responses)
130
- `content`: Response content types and schemas
131
- `headers`: Response headers
132

133
### Content Definition
134

135
Defines content types and their associated schemas for requests and responses.
136

137
```python { .api }
138
@dataclass
139
class Content:
140
    type: Union[ContentType, LooseContentType]
141
    schema: Schema
142
    example: Optional[Any] = None
143
    examples: dict[str, Any] = field(default_factory=dict)
144
```
145

146
**Properties:**
147
- `type`: MIME content type (application/json, text/xml, etc.)
148
- `schema`: Schema definition for the content
149
- `example`: Single example value
150
- `examples`: Named collection of example values
151

152
### Header Definition
153

154
Defines HTTP headers for responses.
155

156
```python { .api }
157
@dataclass
158
class Header:
159
    name: str
160
    schema: Schema
161
    description: Optional[str] = None
162
    required: Optional[bool] = field(default=False)
163
    deprecated: Optional[bool] = field(default=False)
164
    extensions: Optional[dict] = field(default_factory=dict)
165
```
166

167
**Properties:**
168
- `name`: Header name
169
- `schema`: Header value schema
170
- `description`: Header description
171
- `required`: Whether the header is required
172
- `deprecated`: Whether the header is deprecated
173
- `extensions`: Custom header extensions
174

175
### Usage Examples
176

177
Access all paths and operations:
178
```python
179
from openapi_parser import parse
180

181
spec = parse('api-spec.yml')
182

183
# List all paths and their operations
184
for path in spec.paths:
185
    print(f"Path: {path.url}")
186
    if path.summary:
187
        print(f"  Summary: {path.summary}")
188
    
189
    # List operations for this path
190
    for operation in path.operations:
191
        print(f"  {operation.method.value.upper()}: {operation.summary or 'No summary'}")
192
        
193
        # Show operation ID if present
194
        if operation.operation_id:
195
            print(f"    Operation ID: {operation.operation_id}")
196
        
197
        # Show tags
198
        if operation.tags:
199
            print(f"    Tags: {', '.join(operation.tags)}")
200
```
201

202
Examine operation parameters:
203
```python
204
# Find operations with parameters
205
for path in spec.paths:
206
    for operation in path.operations:
207
        all_params = path.parameters + operation.parameters
208
        
209
        if all_params:
210
            print(f"{operation.method.value.upper()} {path.url}")
211
            
212
            for param in all_params:
213
                location = param.location.value
214
                required = "required" if param.required else "optional"
215
                print(f"  {param.name} ({location}, {required})")
216
                
217
                if param.description:
218
                    print(f"    Description: {param.description}")
219
```
220

221
Examine request bodies and responses:
222
```python
223
# Check operations with request bodies
224
for path in spec.paths:
225
    for operation in path.operations:
226
        if operation.request_body:
227
            print(f"{operation.method.value.upper()} {path.url}")
228
            print(f"  Request body required: {operation.request_body.required}")
229
            
230
            # Show supported content types
231
            for content in operation.request_body.content:
232
                print(f"    Content-Type: {content.type}")
233
                print(f"    Schema: {content.schema.type.value}")
234
        
235
        # Show responses
236
        for response in operation.responses:
237
            if response.code:
238
                print(f"  Response {response.code}: {response.description}")
239
            else:
240
                print(f"  Default response: {response.description}")
241
            
242
            # Show response content types
243
            if response.content:
244
                for content in response.content:
245
                    print(f"    Content-Type: {content.type}")
246
```
247

248
Working with content types:
249
```python
250
# Find all content types used in the API
251
content_types = set()
252

253
for path in spec.paths:
254
    for operation in path.operations:
255
        # Request body content types
256
        if operation.request_body:
257
            for content in operation.request_body.content:
258
                content_types.add(str(content.type))
259
        
260
        # Response content types
261
        for response in operation.responses:
262
            if response.content:
263
                for content in response.content:
264
                    content_types.add(str(content.type))
265

266
print("Used content types:")
267
for ct in sorted(content_types):
268
    print(f"  {ct}")
269
```