wapiti-swagger 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Nicolas Surribas
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,177 @@
1
+ Metadata-Version: 2.1
2
+ Name: wapiti-swagger
3
+ Version: 0.1.0
4
+ Summary: A library for parsing and generating request bodies from Swagger/OpenAPI specifications.
5
+ Author-email: Nicolas Surribas <nicolas.surribas@gmail.com>
6
+ License: MIT
7
+ Keywords: swagger,openapi,wapiti,parser
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: License :: OSI Approved :: MIT License
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Topic :: Software Development :: Libraries
12
+ Classifier: Topic :: Internet :: WWW/HTTP
13
+ Requires-Python: >=3.9
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: PyYAML>=6.0
17
+
18
+ # **Wapiti Swagger Parser**
19
+
20
+ ![License](https://img.shields.io/github/license/wapiti-scanner/wapiti_swagger)
21
+ ![Python Versions](https://img.shields.io/badge/python-3.8%20|%203.9%20|%203.10%20|%203.11%20|%203.12-blue)
22
+
23
+ ## **Project Description**
24
+
25
+ The **Wapiti Swagger Parser** is a Python library designed to parse Swagger (OpenAPI) specifications and extract the necessary information to generate valid HTTP requests. It focuses on providing a clean, programmatic interface for analyzing Swagger files and creating request templates without relying on external tools for OpenAPI processing.
26
+
27
+ This library is particularly useful for scenarios where only the request generation requirements are of interest, such as:
28
+
29
+ - Automated testing and validation of APIs.
30
+ - Dynamic request generation for web vulnerability scanners (like Wapiti).
31
+ - Custom API tooling.
32
+
33
+ The library is lightweight, relying only on Python's built-in `json` library and `PyYAML` for file parsing, and it avoids heavy dependencies on larger OpenAPI frameworks.
34
+
35
+ ---
36
+
37
+ ## **Key Features**
38
+
39
+ - **Request Extraction**:
40
+ - Parses all HTTP requests (methods, paths, parameters) defined in the Swagger file.
41
+ - **Schema Handling**:
42
+ - Resolves `$ref` references in schemas, including handling circular references gracefully.
43
+ - **Custom Types**:
44
+ - Identifies and retains custom types (e.g., enumerated values, objects) for enhanced request understanding.
45
+ - **Request Body Generation**:
46
+ - Automatically generates example request bodies based on schema definitions.
47
+ - **Metadata Extraction**:
48
+ - Captures root-level metadata like `host`, `basePath`, `servers`, and `schemes`.
49
+ - **Supports Swagger 2.0 and OpenAPI 3.x**:
50
+ - Works with both specification versions seamlessly.
51
+
52
+ ---
53
+
54
+ ## **Usage Example**
55
+
56
+ ```python
57
+ from wapiti_swagger.parser import parse, generate_request_body_from_schema
58
+
59
+ # Load and parse a Swagger file
60
+ parsed = parse("swagger.json")
61
+
62
+ # List all available requests
63
+ for request in parsed.requests:
64
+ print(request)
65
+
66
+ # Generate an example request body for a specific request (here one expecting JSON input)
67
+ request_body = generate_request_body_from_schema(
68
+ schema=request.parameters[0].schema, # Use the schema of the first parameter
69
+ resolved_components=parsed.components
70
+ )
71
+ print("Example request body:", request_body)
72
+ ```
73
+
74
+ ---
75
+
76
+ ## **Why Use This Library?**
77
+
78
+ Unlike general-purpose OpenAPI parsers, this library is optimized for specific use cases like generating valid requests for API testing, scanning, or mocking. It is lightweight, customizable, and avoids unnecessary processing of response definitions or additional metadata unrelated to request generation.
79
+
80
+ ---
81
+
82
+ ## **Methods in `parser` Module**
83
+
84
+ ### 1. `parse(file_path: str) -> ParsedSwagger`
85
+ Parses a Swagger/OpenAPI specification file and returns a `ParsedSwagger` object containing the following:
86
+ - **Requests:** List of `SwaggerRequest` objects extracted from paths.
87
+ - **Components:** Preprocessed and resolved components (e.g., schemas, parameters).
88
+ - **Metadata:** High-level metadata like `host`, `basePath`, and `servers`.
89
+
90
+ **Parameters:**
91
+ - `file_path` (str): Path to the Swagger/OpenAPI file (JSON or YAML).
92
+
93
+ **Returns:**
94
+ - `ParsedSwagger`: Object containing parsed requests, components, and metadata.
95
+
96
+ ---
97
+
98
+ ### 2. `extract_requests(data: dict) -> List[SwaggerRequest]`
99
+ Extracts all HTTP requests from the `paths` section of the Swagger specification.
100
+
101
+ **Parameters:**
102
+ - `data` (dict): The full Swagger/OpenAPI specification as a dictionary.
103
+
104
+ **Returns:**
105
+ - `List[SwaggerRequest]`: A list of requests with details like method, path, parameters, and request bodies.
106
+
107
+ ---
108
+
109
+ ### 3. `extract_request_body(request_body: dict) -> List[Parameter]`
110
+ Extracts parameters from the `requestBody` section of a Swagger path operation.
111
+ Handles multiple media types (e.g., `application/json`, `text/json`).
112
+
113
+ **Parameters:**
114
+ - `request_body` (dict): The `requestBody` definition for a path operation.
115
+
116
+ **Returns:**
117
+ - `List[Parameter]`: A list of parameters with details like media type, schema, and custom type.
118
+
119
+ ---
120
+
121
+ ### 4. `extract_parameter(param: dict) -> Parameter`
122
+ Parses a single parameter from the `parameters` section of a Swagger path operation.
123
+
124
+ **Parameters:**
125
+ - `param` (dict): The parameter definition.
126
+
127
+ **Returns:**
128
+ - `Parameter`: Object representing the parameter with details like name, location, type, and schema.
129
+
130
+ ---
131
+
132
+ ### 5. `parse_components(components: dict) -> Dict[str, Dict]`
133
+ Resolves and preprocesses all components (e.g., schemas, parameters) from the `components` section of the Swagger specification.
134
+
135
+ **Parameters:**
136
+ - `components` (dict): The `components` section of the Swagger specification.
137
+
138
+ **Returns:**
139
+ - `Dict[str, Dict]`: Resolved and preprocessed components organized by type (e.g., schemas, parameters).
140
+
141
+ ---
142
+
143
+ ### 6. `resolve_schema(schema: dict, resolved_components: dict, visited_refs: set) -> dict`
144
+ Recursively resolves `$ref` references in schemas while avoiding circular references.
145
+
146
+ **Parameters:**
147
+ - `schema` (dict): The schema to resolve.
148
+ - `resolved_components` (dict): Preprocessed components for reference resolution.
149
+ - `visited_refs` (set): Tracks references to avoid circular references.
150
+
151
+ **Returns:**
152
+ - `dict`: Fully resolved schema.
153
+
154
+ ---
155
+
156
+ ### 7. `extract_metadata(data: dict) -> Dict[str, Any]`
157
+ Extracts high-level metadata from the root of the Swagger specification, such as `host`, `basePath`, and `servers`.
158
+
159
+ **Parameters:**
160
+ - `data` (dict): The full Swagger/OpenAPI specification.
161
+
162
+ **Returns:**
163
+ - `Dict[str, Any]`: Metadata like `host`, `basePath`, `schemes`, and `servers`.
164
+
165
+ ---
166
+
167
+ ### 8. `generate_request_body_from_schema(schema: dict, resolved_components: dict) -> Optional[Union[dict, list, str, int, bool]]`
168
+ Generates an example request body based on a schema definition.
169
+
170
+ **Parameters:**
171
+ - `schema` (dict): The schema definition.
172
+ - `resolved_components` (dict): Resolved components for reference resolution.
173
+
174
+ **Returns:**
175
+ - `Optional[Union[dict, list, str, int, bool]]`: An example request body.
176
+
177
+ ---
@@ -0,0 +1,160 @@
1
+ # **Wapiti Swagger Parser**
2
+
3
+ ![License](https://img.shields.io/github/license/wapiti-scanner/wapiti_swagger)
4
+ ![Python Versions](https://img.shields.io/badge/python-3.8%20|%203.9%20|%203.10%20|%203.11%20|%203.12-blue)
5
+
6
+ ## **Project Description**
7
+
8
+ The **Wapiti Swagger Parser** is a Python library designed to parse Swagger (OpenAPI) specifications and extract the necessary information to generate valid HTTP requests. It focuses on providing a clean, programmatic interface for analyzing Swagger files and creating request templates without relying on external tools for OpenAPI processing.
9
+
10
+ This library is particularly useful for scenarios where only the request generation requirements are of interest, such as:
11
+
12
+ - Automated testing and validation of APIs.
13
+ - Dynamic request generation for web vulnerability scanners (like Wapiti).
14
+ - Custom API tooling.
15
+
16
+ The library is lightweight, relying only on Python's built-in `json` library and `PyYAML` for file parsing, and it avoids heavy dependencies on larger OpenAPI frameworks.
17
+
18
+ ---
19
+
20
+ ## **Key Features**
21
+
22
+ - **Request Extraction**:
23
+ - Parses all HTTP requests (methods, paths, parameters) defined in the Swagger file.
24
+ - **Schema Handling**:
25
+ - Resolves `$ref` references in schemas, including handling circular references gracefully.
26
+ - **Custom Types**:
27
+ - Identifies and retains custom types (e.g., enumerated values, objects) for enhanced request understanding.
28
+ - **Request Body Generation**:
29
+ - Automatically generates example request bodies based on schema definitions.
30
+ - **Metadata Extraction**:
31
+ - Captures root-level metadata like `host`, `basePath`, `servers`, and `schemes`.
32
+ - **Supports Swagger 2.0 and OpenAPI 3.x**:
33
+ - Works with both specification versions seamlessly.
34
+
35
+ ---
36
+
37
+ ## **Usage Example**
38
+
39
+ ```python
40
+ from wapiti_swagger.parser import parse, generate_request_body_from_schema
41
+
42
+ # Load and parse a Swagger file
43
+ parsed = parse("swagger.json")
44
+
45
+ # List all available requests
46
+ for request in parsed.requests:
47
+ print(request)
48
+
49
+ # Generate an example request body for a specific request (here one expecting JSON input)
50
+ request_body = generate_request_body_from_schema(
51
+ schema=request.parameters[0].schema, # Use the schema of the first parameter
52
+ resolved_components=parsed.components
53
+ )
54
+ print("Example request body:", request_body)
55
+ ```
56
+
57
+ ---
58
+
59
+ ## **Why Use This Library?**
60
+
61
+ Unlike general-purpose OpenAPI parsers, this library is optimized for specific use cases like generating valid requests for API testing, scanning, or mocking. It is lightweight, customizable, and avoids unnecessary processing of response definitions or additional metadata unrelated to request generation.
62
+
63
+ ---
64
+
65
+ ## **Methods in `parser` Module**
66
+
67
+ ### 1. `parse(file_path: str) -> ParsedSwagger`
68
+ Parses a Swagger/OpenAPI specification file and returns a `ParsedSwagger` object containing the following:
69
+ - **Requests:** List of `SwaggerRequest` objects extracted from paths.
70
+ - **Components:** Preprocessed and resolved components (e.g., schemas, parameters).
71
+ - **Metadata:** High-level metadata like `host`, `basePath`, and `servers`.
72
+
73
+ **Parameters:**
74
+ - `file_path` (str): Path to the Swagger/OpenAPI file (JSON or YAML).
75
+
76
+ **Returns:**
77
+ - `ParsedSwagger`: Object containing parsed requests, components, and metadata.
78
+
79
+ ---
80
+
81
+ ### 2. `extract_requests(data: dict) -> List[SwaggerRequest]`
82
+ Extracts all HTTP requests from the `paths` section of the Swagger specification.
83
+
84
+ **Parameters:**
85
+ - `data` (dict): The full Swagger/OpenAPI specification as a dictionary.
86
+
87
+ **Returns:**
88
+ - `List[SwaggerRequest]`: A list of requests with details like method, path, parameters, and request bodies.
89
+
90
+ ---
91
+
92
+ ### 3. `extract_request_body(request_body: dict) -> List[Parameter]`
93
+ Extracts parameters from the `requestBody` section of a Swagger path operation.
94
+ Handles multiple media types (e.g., `application/json`, `text/json`).
95
+
96
+ **Parameters:**
97
+ - `request_body` (dict): The `requestBody` definition for a path operation.
98
+
99
+ **Returns:**
100
+ - `List[Parameter]`: A list of parameters with details like media type, schema, and custom type.
101
+
102
+ ---
103
+
104
+ ### 4. `extract_parameter(param: dict) -> Parameter`
105
+ Parses a single parameter from the `parameters` section of a Swagger path operation.
106
+
107
+ **Parameters:**
108
+ - `param` (dict): The parameter definition.
109
+
110
+ **Returns:**
111
+ - `Parameter`: Object representing the parameter with details like name, location, type, and schema.
112
+
113
+ ---
114
+
115
+ ### 5. `parse_components(components: dict) -> Dict[str, Dict]`
116
+ Resolves and preprocesses all components (e.g., schemas, parameters) from the `components` section of the Swagger specification.
117
+
118
+ **Parameters:**
119
+ - `components` (dict): The `components` section of the Swagger specification.
120
+
121
+ **Returns:**
122
+ - `Dict[str, Dict]`: Resolved and preprocessed components organized by type (e.g., schemas, parameters).
123
+
124
+ ---
125
+
126
+ ### 6. `resolve_schema(schema: dict, resolved_components: dict, visited_refs: set) -> dict`
127
+ Recursively resolves `$ref` references in schemas while avoiding circular references.
128
+
129
+ **Parameters:**
130
+ - `schema` (dict): The schema to resolve.
131
+ - `resolved_components` (dict): Preprocessed components for reference resolution.
132
+ - `visited_refs` (set): Tracks references to avoid circular references.
133
+
134
+ **Returns:**
135
+ - `dict`: Fully resolved schema.
136
+
137
+ ---
138
+
139
+ ### 7. `extract_metadata(data: dict) -> Dict[str, Any]`
140
+ Extracts high-level metadata from the root of the Swagger specification, such as `host`, `basePath`, and `servers`.
141
+
142
+ **Parameters:**
143
+ - `data` (dict): The full Swagger/OpenAPI specification.
144
+
145
+ **Returns:**
146
+ - `Dict[str, Any]`: Metadata like `host`, `basePath`, `schemes`, and `servers`.
147
+
148
+ ---
149
+
150
+ ### 8. `generate_request_body_from_schema(schema: dict, resolved_components: dict) -> Optional[Union[dict, list, str, int, bool]]`
151
+ Generates an example request body based on a schema definition.
152
+
153
+ **Parameters:**
154
+ - `schema` (dict): The schema definition.
155
+ - `resolved_components` (dict): Resolved components for reference resolution.
156
+
157
+ **Returns:**
158
+ - `Optional[Union[dict, list, str, int, bool]]`: An example request body.
159
+
160
+ ---
@@ -0,0 +1,27 @@
1
+ [build-system]
2
+ requires = ["setuptools>=42", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "wapiti-swagger"
7
+ version = "0.1.0"
8
+ description = "A library for parsing and generating request bodies from Swagger/OpenAPI specifications."
9
+ readme = "README.md"
10
+ license = {text = "MIT"}
11
+ authors = [
12
+ {name="Nicolas Surribas", email="nicolas.surribas@gmail.com"}
13
+ ]
14
+ keywords = ["swagger", "openapi", "wapiti", "parser"]
15
+ classifiers = [
16
+ "Programming Language :: Python :: 3",
17
+ "License :: OSI Approved :: MIT License",
18
+ "Operating System :: OS Independent",
19
+ "Topic :: Software Development :: Libraries",
20
+ "Topic :: Internet :: WWW/HTTP",
21
+ ]
22
+ dependencies = ["PyYAML>=6.0"] # Add any other required dependencies here
23
+ requires-python = ">=3.9"
24
+
25
+ [tool.setuptools.packages.find]
26
+ where = ["wapiti_swagger"]
27
+
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,249 @@
1
+ import pytest
2
+
3
+ from wapiti_swagger.parser import generate_request_body_from_schema, parse
4
+
5
+ # Save the complex Swagger file content as a string
6
+ COMPLEX_SWAGGER = """
7
+ {
8
+ "openapi": "3.0.0",
9
+ "info": {
10
+ "title": "Complex API Example",
11
+ "version": "1.0.0"
12
+ },
13
+ "paths": {
14
+ "/api/ComplexObject": {
15
+ "post": {
16
+ "summary": "Create a Complex Object",
17
+ "requestBody": {
18
+ "required": true,
19
+ "content": {
20
+ "application/json": {
21
+ "schema": {
22
+ "$ref": "#/components/schemas/ComplexObject"
23
+ }
24
+ }
25
+ }
26
+ }
27
+ }
28
+ }
29
+ },
30
+ "components": {
31
+ "schemas": {
32
+ "ComplexObject": {
33
+ "type": "object",
34
+ "properties": {
35
+ "id": {
36
+ "type": "integer",
37
+ "format": "int64"
38
+ },
39
+ "name": {
40
+ "type": "string"
41
+ },
42
+ "tags": {
43
+ "type": "array",
44
+ "items": {
45
+ "type": "string"
46
+ }
47
+ },
48
+ "children": {
49
+ "type": "array",
50
+ "items": {
51
+ "$ref": "#/components/schemas/ChildObject"
52
+ }
53
+ }
54
+ },
55
+ "required": ["id", "name", "children"]
56
+ },
57
+ "ChildObject": {
58
+ "type": "object",
59
+ "properties": {
60
+ "type": {
61
+ "type": "string",
62
+ "enum": ["TypeA", "TypeB", "TypeC"]
63
+ },
64
+ "details": {
65
+ "$ref": "#/components/schemas/DetailObject"
66
+ }
67
+ },
68
+ "required": ["type"]
69
+ },
70
+ "DetailObject": {
71
+ "type": "object",
72
+ "properties": {
73
+ "description": {
74
+ "type": "string"
75
+ },
76
+ "value": {
77
+ "type": "number",
78
+ "format": "double"
79
+ }
80
+ },
81
+ "required": ["description"]
82
+ }
83
+ }
84
+ }
85
+ }
86
+ """
87
+
88
+ @pytest.fixture
89
+ def complex_swagger_file(tmp_path):
90
+ swagger_path = tmp_path / "complex_swagger.json"
91
+ swagger_path.write_text(COMPLEX_SWAGGER)
92
+ return swagger_path
93
+
94
+ def test_generate_request_body_with_complex_object(complex_swagger_file):
95
+ # Parse the Swagger file
96
+ parsed = parse(str(complex_swagger_file))
97
+
98
+ # Find the POST request for /api/ComplexObject
99
+ request = next(req for req in parsed.requests if req.path == "/api/ComplexObject" and req.method == "POST")
100
+
101
+ # Generate the request body for the ComplexObject schema
102
+ request_body = generate_request_body_from_schema(
103
+ schema=request.parameters[0].schema,
104
+ resolved_components=parsed.components
105
+ )
106
+
107
+ # Expected output
108
+ expected_body = {
109
+ "id": 0,
110
+ "name": "example",
111
+ "tags": ["example"],
112
+ "children": [
113
+ {
114
+ "type": "TypeA",
115
+ "details": {
116
+ "description": "example",
117
+ "value": 0.0
118
+ }
119
+ }
120
+ ]
121
+ }
122
+
123
+ # Validate the generated request body
124
+ assert request_body == expected_body
125
+
126
+
127
+
128
+ # Save the Swagger file as a string
129
+ HIERARCHY_SWAGGER = """
130
+ {
131
+ "openapi": "3.0.0",
132
+ "info": {
133
+ "title": "Hierarchy API Example",
134
+ "version": "1.0.0"
135
+ },
136
+ "paths": {
137
+ "/api/ParentObject": {
138
+ "post": {
139
+ "summary": "Create a Parent Object",
140
+ "requestBody": {
141
+ "required": true,
142
+ "content": {
143
+ "application/json": {
144
+ "schema": {
145
+ "$ref": "#/components/schemas/ParentObject"
146
+ }
147
+ }
148
+ }
149
+ }
150
+ }
151
+ }
152
+ },
153
+ "components": {
154
+ "schemas": {
155
+ "ParentObject": {
156
+ "type": "object",
157
+ "properties": {
158
+ "parentId": {
159
+ "type": "integer",
160
+ "format": "int64"
161
+ },
162
+ "parentName": {
163
+ "type": "string"
164
+ },
165
+ "children": {
166
+ "type": "array",
167
+ "items": {
168
+ "$ref": "#/components/schemas/ChildObject"
169
+ }
170
+ }
171
+ },
172
+ "required": ["parentId", "parentName"]
173
+ },
174
+ "ChildObject": {
175
+ "type": "object",
176
+ "properties": {
177
+ "childId": {
178
+ "type": "integer",
179
+ "format": "int64"
180
+ },
181
+ "childName": {
182
+ "type": "string"
183
+ },
184
+ "grandchildren": {
185
+ "type": "array",
186
+ "items": {
187
+ "$ref": "#/components/schemas/GrandchildObject"
188
+ }
189
+ }
190
+ },
191
+ "required": ["childId", "childName"]
192
+ },
193
+ "GrandchildObject": {
194
+ "type": "object",
195
+ "properties": {
196
+ "grandchildId": {
197
+ "type": "integer",
198
+ "format": "int64"
199
+ },
200
+ "grandchildName": {
201
+ "type": "string"
202
+ }
203
+ },
204
+ "required": ["grandchildId", "grandchildName"]
205
+ }
206
+ }
207
+ }
208
+ }
209
+ """
210
+
211
+ @pytest.fixture
212
+ def hierarchy_swagger_file(tmp_path):
213
+ swagger_path = tmp_path / "hierarchy_swagger.json"
214
+ swagger_path.write_text(HIERARCHY_SWAGGER)
215
+ return swagger_path
216
+
217
+ def test_generate_request_body_with_hierarchy(hierarchy_swagger_file):
218
+ # Parse the Swagger file
219
+ parsed = parse(str(hierarchy_swagger_file))
220
+
221
+ # Find the POST request for /api/ParentObject
222
+ request = next(req for req in parsed.requests if req.path == "/api/ParentObject" and req.method == "POST")
223
+
224
+ # Generate the request body for the ParentObject schema
225
+ request_body = generate_request_body_from_schema(
226
+ schema=request.parameters[0].schema,
227
+ resolved_components=parsed.components
228
+ )
229
+
230
+ # Expected output
231
+ expected_body = {
232
+ "parentId": 0,
233
+ "parentName": "example",
234
+ "children": [
235
+ {
236
+ "childId": 0,
237
+ "childName": "example",
238
+ "grandchildren": [
239
+ {
240
+ "grandchildId": 0,
241
+ "grandchildName": "example"
242
+ }
243
+ ]
244
+ }
245
+ ]
246
+ }
247
+
248
+ # Validate the generated request body
249
+ assert request_body == expected_body
@@ -0,0 +1,80 @@
1
+ from wapiti_swagger.parser import extract_request_body, parse_components
2
+
3
+ components_data = {
4
+ "schemas": {
5
+ "BaseSchema": {
6
+ "type": "object",
7
+ "properties": {
8
+ "id": {"type": "string"}
9
+ }
10
+ },
11
+ "DerivedSchema": {
12
+ "$ref": "#/components/schemas/BaseSchema"
13
+ }
14
+ }
15
+ }
16
+
17
+ def test_parse_components():
18
+ resolved = parse_components(components_data)
19
+
20
+ # Assertions for resolved components
21
+ assert "BaseSchema" in resolved["schemas"]
22
+ assert "DerivedSchema" in resolved["schemas"]
23
+ assert resolved["schemas"]["DerivedSchema"] == resolved["schemas"]["BaseSchema"]
24
+
25
+
26
+
27
+ reduced_swagger_with_custom_type = {
28
+ "paths": {
29
+ "/api/AmaApproval/report/userbehavior": {
30
+ "post": {
31
+ "requestBody": {
32
+ "content": {
33
+ "application/json": {
34
+ "schema": {
35
+ "$ref": "#/components/schemas/AmaApprovalBehaviorInput"
36
+ }
37
+ },
38
+ "text/json": {
39
+ "schema": {
40
+ "$ref": "#/components/schemas/AmaApprovalBehaviorInput"
41
+ }
42
+ }
43
+ }
44
+ }
45
+ }
46
+ }
47
+ },
48
+ "components": {
49
+ "schemas": {
50
+ "AmaApprovalBehaviorInput": {
51
+ "type": "object",
52
+ "properties": {
53
+ "behaviorType": {"$ref": "#/components/schemas/EnumAmaUserBehaviorType"},
54
+ "docFindingCategory": {"$ref": "#/components/schemas/EnumAmaDocFindingCategory"}
55
+ }
56
+ },
57
+ "EnumAmaUserBehaviorType": {"type": "string", "enum": ["VIEWED", "EDITED"]},
58
+ "EnumAmaDocFindingCategory": {"type": "string", "enum": ["FINDING1", "FINDING2"]}
59
+ }
60
+ }
61
+ }
62
+
63
+
64
+ def test_extract_request_body_with_custom_type():
65
+ # Extract request body parameters
66
+ request_body = reduced_swagger_with_custom_type["paths"]["/api/AmaApproval/report/userbehavior"]["post"]["requestBody"]
67
+ parameters = extract_request_body(request_body)
68
+
69
+ # Assertions for parameters
70
+ assert len(parameters) == 2 # Two media types
71
+
72
+ # Check first parameter
73
+ param_json = parameters[0]
74
+ assert param_json.media_type == "application/json"
75
+ assert param_json.custom_type == "AmaApprovalBehaviorInput"
76
+
77
+ # Check second parameter
78
+ param_text_json = parameters[1]
79
+ assert param_text_json.media_type == "text/json"
80
+ assert param_text_json.custom_type == "AmaApprovalBehaviorInput"
@@ -0,0 +1,101 @@
1
+ from wapiti_swagger.models import Parameter, SwaggerRequest
2
+ from wapiti_swagger.parser import extract_parameter, extract_requests
3
+
4
+
5
+ def test_extract_parameter_with_inline_schema():
6
+ param = {
7
+ "name": "end",
8
+ "in": "query",
9
+ "schema": {
10
+ "type": "string",
11
+ "format": "date-time",
12
+ "nullable": False
13
+ }
14
+ }
15
+
16
+ extracted_param = extract_parameter(param)
17
+
18
+ assert extracted_param.name == "end"
19
+ assert extracted_param.location == "query"
20
+ assert extracted_param.param_type == "string"
21
+ assert extracted_param.param_format == "date-time"
22
+ assert extracted_param.nullable is False
23
+ assert extracted_param.default is None
24
+
25
+
26
+
27
+ reduced_swagger_data = {
28
+ "paths": {
29
+ "/api/WechatCall/GetSignature": {
30
+ "post": {
31
+ "tags": ["WechatCall"],
32
+ "summary": "Get signature for WeChat API calls",
33
+ "parameters": [
34
+ {
35
+ "name": "appId",
36
+ "in": "query",
37
+ "description": "The application ID",
38
+ "required": True,
39
+ "schema": {
40
+ "type": "string"
41
+ }
42
+ },
43
+ {
44
+ "name": "timestamp",
45
+ "in": "query",
46
+ "description": "The timestamp",
47
+ "schema": {
48
+ "$ref": "#/components/schemas/Timestamp"
49
+ }
50
+ }
51
+ ]
52
+ }
53
+ }
54
+ },
55
+ "components": {
56
+ "schemas": {
57
+ "Timestamp": {
58
+ "type": "string",
59
+ "format": "date-time",
60
+ "nullable": False
61
+ }
62
+ }
63
+ }
64
+ }
65
+
66
+
67
+ def test_extract_requests():
68
+ # Call extract_requests with the reduced Swagger data
69
+ extracted_requests = extract_requests(reduced_swagger_data)
70
+
71
+ # Assertions for the extracted request
72
+ assert len(extracted_requests) == 1 # Only one request should be extracted
73
+ request = extracted_requests[0]
74
+ assert isinstance(request, SwaggerRequest)
75
+ assert request.path == "/api/WechatCall/GetSignature"
76
+ assert request.method == "POST"
77
+ assert request.summary == "Get signature for WeChat API calls"
78
+ assert len(request.parameters) == 2 # Two parameters should be extracted
79
+
80
+ # Assertions for the first parameter (appId)
81
+ param_app_id = request.parameters[0]
82
+ assert isinstance(param_app_id, Parameter)
83
+ assert param_app_id.name == "appId"
84
+ assert param_app_id.location == "query"
85
+ assert param_app_id.description == "The application ID"
86
+ assert param_app_id.required is True
87
+ assert param_app_id.param_type == "string"
88
+ assert param_app_id.param_format == ""
89
+ assert param_app_id.nullable is False
90
+
91
+ # Assertions for the second parameter (timestamp)
92
+ param_timestamp = request.parameters[1]
93
+ assert isinstance(param_timestamp, Parameter)
94
+ assert param_timestamp.name == "timestamp"
95
+ assert param_timestamp.location == "query"
96
+ assert param_timestamp.description == "The timestamp"
97
+ assert param_timestamp.required is False
98
+ assert param_timestamp.param_type == ""
99
+ assert param_timestamp.custom_type == "Timestamp"
100
+ assert param_timestamp.param_format == ""
101
+ assert param_timestamp.nullable is False
@@ -0,0 +1,147 @@
1
+ from wapiti_swagger.models import SwaggerRequest
2
+ from wapiti_swagger.parser import extract_request_body, extract_requests
3
+
4
+ swagger_data_with_body = {
5
+ "paths": {
6
+ "/api/WechatCall/GetSignature": {
7
+ "post": {
8
+ "tags": ["WechatCall"],
9
+ "summary": "Get signature for WeChat API calls",
10
+ "parameters": [
11
+ {
12
+ "name": "appId",
13
+ "in": "query",
14
+ "description": "The application ID",
15
+ "required": True,
16
+ "schema": {
17
+ "type": "string"
18
+ }
19
+ }
20
+ ],
21
+ "requestBody": {
22
+ "content": {
23
+ "application/json": {
24
+ "schema": {
25
+ "$ref": "#/components/schemas/SignatureRequest"
26
+ }
27
+ }
28
+ }
29
+ }
30
+ }
31
+ }
32
+ },
33
+ "components": {
34
+ "schemas": {
35
+ "SignatureRequest": {
36
+ "type": "object",
37
+ "properties": {
38
+ "timestamp": {
39
+ "type": "string",
40
+ "format": "date-time"
41
+ },
42
+ "nonce": {
43
+ "type": "string"
44
+ }
45
+ },
46
+ "required": ["timestamp"]
47
+ }
48
+ }
49
+ }
50
+ }
51
+
52
+ def test_extract_requests_with_request_body():
53
+ # Call extract_requests with the reduced Swagger data
54
+ extracted_requests = extract_requests(swagger_data_with_body)
55
+
56
+ # Assertions for the extracted request
57
+ assert len(extracted_requests) == 1
58
+ request = extracted_requests[0]
59
+ assert isinstance(request, SwaggerRequest)
60
+ assert request.path == "/api/WechatCall/GetSignature"
61
+ assert request.method == "POST"
62
+ assert request.summary == "Get signature for WeChat API calls"
63
+
64
+ # Check parameters
65
+ assert len(request.parameters) == 2 # One query param + one body params
66
+
67
+ # Query parameter: appId
68
+ param_app_id = request.parameters[0]
69
+ assert param_app_id.name == "appId"
70
+ assert param_app_id.location == "query"
71
+ assert param_app_id.param_type == "string"
72
+ assert param_app_id.custom_type is None
73
+
74
+ # Body parameter: timestamp
75
+ param_timestamp = request.parameters[1]
76
+ assert param_timestamp.name == "body"
77
+ assert param_timestamp.location == "body"
78
+ assert param_timestamp.param_type == ""
79
+ assert param_timestamp.custom_type == "SignatureRequest"
80
+ assert param_timestamp.description == "Request body for application/json"
81
+
82
+
83
+ swagger_with_multiple_content_types = {
84
+ "paths": {
85
+ "/api/WechatCall/GetSignature": {
86
+ "post": {
87
+ "requestBody": {
88
+ "content": {
89
+ "application/json": {
90
+ "schema": {
91
+ "$ref": "#/components/schemas/SignatureRequest"
92
+ }
93
+ },
94
+ "application/xml": {
95
+ "schema": {
96
+ "$ref": "#/components/schemas/SignatureRequest"
97
+ }
98
+ }
99
+ }
100
+ }
101
+ }
102
+ }
103
+ },
104
+ "components": {
105
+ "schemas": {
106
+ "SignatureRequest": {
107
+ "type": "object",
108
+ "properties": {
109
+ "timestamp": {
110
+ "type": "string",
111
+ "format": "date-time"
112
+ },
113
+ "nonce": {
114
+ "type": "string"
115
+ }
116
+ },
117
+ "required": ["timestamp"]
118
+ }
119
+ }
120
+ }
121
+ }
122
+
123
+
124
+ def test_extract_request_body_with_media_type():
125
+ # Call extract_request_body with reduced Swagger data
126
+ request_body = swagger_with_multiple_content_types["paths"]["/api/WechatCall/GetSignature"]["post"]["requestBody"]
127
+
128
+ parameters = extract_request_body(request_body)
129
+
130
+ # Assertions for parameters
131
+ assert len(parameters) == 2 # One parameter per content type
132
+
133
+ # Check application/json parameter
134
+ param_json = parameters[0]
135
+ assert param_json.name == "body"
136
+ assert param_json.media_type == "application/json"
137
+ assert param_json.description == "Request body for application/json"
138
+ assert param_json.param_type == ""
139
+ assert param_json.custom_type == "SignatureRequest"
140
+
141
+ # Check application/xml parameter
142
+ param_xml = parameters[1]
143
+ assert param_xml.name == "body"
144
+ assert param_xml.media_type == "application/xml"
145
+ assert param_xml.description == "Request body for application/xml"
146
+ assert param_xml.param_type == ""
147
+ assert param_xml.custom_type == "SignatureRequest"
@@ -0,0 +1,177 @@
1
+ Metadata-Version: 2.1
2
+ Name: wapiti-swagger
3
+ Version: 0.1.0
4
+ Summary: A library for parsing and generating request bodies from Swagger/OpenAPI specifications.
5
+ Author-email: Nicolas Surribas <nicolas.surribas@gmail.com>
6
+ License: MIT
7
+ Keywords: swagger,openapi,wapiti,parser
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: License :: OSI Approved :: MIT License
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Topic :: Software Development :: Libraries
12
+ Classifier: Topic :: Internet :: WWW/HTTP
13
+ Requires-Python: >=3.9
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: PyYAML>=6.0
17
+
18
+ # **Wapiti Swagger Parser**
19
+
20
+ ![License](https://img.shields.io/github/license/wapiti-scanner/wapiti_swagger)
21
+ ![Python Versions](https://img.shields.io/badge/python-3.8%20|%203.9%20|%203.10%20|%203.11%20|%203.12-blue)
22
+
23
+ ## **Project Description**
24
+
25
+ The **Wapiti Swagger Parser** is a Python library designed to parse Swagger (OpenAPI) specifications and extract the necessary information to generate valid HTTP requests. It focuses on providing a clean, programmatic interface for analyzing Swagger files and creating request templates without relying on external tools for OpenAPI processing.
26
+
27
+ This library is particularly useful for scenarios where only the request generation requirements are of interest, such as:
28
+
29
+ - Automated testing and validation of APIs.
30
+ - Dynamic request generation for web vulnerability scanners (like Wapiti).
31
+ - Custom API tooling.
32
+
33
+ The library is lightweight, relying only on Python's built-in `json` library and `PyYAML` for file parsing, and it avoids heavy dependencies on larger OpenAPI frameworks.
34
+
35
+ ---
36
+
37
+ ## **Key Features**
38
+
39
+ - **Request Extraction**:
40
+ - Parses all HTTP requests (methods, paths, parameters) defined in the Swagger file.
41
+ - **Schema Handling**:
42
+ - Resolves `$ref` references in schemas, including handling circular references gracefully.
43
+ - **Custom Types**:
44
+ - Identifies and retains custom types (e.g., enumerated values, objects) for enhanced request understanding.
45
+ - **Request Body Generation**:
46
+ - Automatically generates example request bodies based on schema definitions.
47
+ - **Metadata Extraction**:
48
+ - Captures root-level metadata like `host`, `basePath`, `servers`, and `schemes`.
49
+ - **Supports Swagger 2.0 and OpenAPI 3.x**:
50
+ - Works with both specification versions seamlessly.
51
+
52
+ ---
53
+
54
+ ## **Usage Example**
55
+
56
+ ```python
57
+ from wapiti_swagger.parser import parse, generate_request_body_from_schema
58
+
59
+ # Load and parse a Swagger file
60
+ parsed = parse("swagger.json")
61
+
62
+ # List all available requests
63
+ for request in parsed.requests:
64
+ print(request)
65
+
66
+ # Generate an example request body for a specific request (here one expecting JSON input)
67
+ request_body = generate_request_body_from_schema(
68
+ schema=request.parameters[0].schema, # Use the schema of the first parameter
69
+ resolved_components=parsed.components
70
+ )
71
+ print("Example request body:", request_body)
72
+ ```
73
+
74
+ ---
75
+
76
+ ## **Why Use This Library?**
77
+
78
+ Unlike general-purpose OpenAPI parsers, this library is optimized for specific use cases like generating valid requests for API testing, scanning, or mocking. It is lightweight, customizable, and avoids unnecessary processing of response definitions or additional metadata unrelated to request generation.
79
+
80
+ ---
81
+
82
+ ## **Methods in `parser` Module**
83
+
84
+ ### 1. `parse(file_path: str) -> ParsedSwagger`
85
+ Parses a Swagger/OpenAPI specification file and returns a `ParsedSwagger` object containing the following:
86
+ - **Requests:** List of `SwaggerRequest` objects extracted from paths.
87
+ - **Components:** Preprocessed and resolved components (e.g., schemas, parameters).
88
+ - **Metadata:** High-level metadata like `host`, `basePath`, and `servers`.
89
+
90
+ **Parameters:**
91
+ - `file_path` (str): Path to the Swagger/OpenAPI file (JSON or YAML).
92
+
93
+ **Returns:**
94
+ - `ParsedSwagger`: Object containing parsed requests, components, and metadata.
95
+
96
+ ---
97
+
98
+ ### 2. `extract_requests(data: dict) -> List[SwaggerRequest]`
99
+ Extracts all HTTP requests from the `paths` section of the Swagger specification.
100
+
101
+ **Parameters:**
102
+ - `data` (dict): The full Swagger/OpenAPI specification as a dictionary.
103
+
104
+ **Returns:**
105
+ - `List[SwaggerRequest]`: A list of requests with details like method, path, parameters, and request bodies.
106
+
107
+ ---
108
+
109
+ ### 3. `extract_request_body(request_body: dict) -> List[Parameter]`
110
+ Extracts parameters from the `requestBody` section of a Swagger path operation.
111
+ Handles multiple media types (e.g., `application/json`, `text/json`).
112
+
113
+ **Parameters:**
114
+ - `request_body` (dict): The `requestBody` definition for a path operation.
115
+
116
+ **Returns:**
117
+ - `List[Parameter]`: A list of parameters with details like media type, schema, and custom type.
118
+
119
+ ---
120
+
121
+ ### 4. `extract_parameter(param: dict) -> Parameter`
122
+ Parses a single parameter from the `parameters` section of a Swagger path operation.
123
+
124
+ **Parameters:**
125
+ - `param` (dict): The parameter definition.
126
+
127
+ **Returns:**
128
+ - `Parameter`: Object representing the parameter with details like name, location, type, and schema.
129
+
130
+ ---
131
+
132
+ ### 5. `parse_components(components: dict) -> Dict[str, Dict]`
133
+ Resolves and preprocesses all components (e.g., schemas, parameters) from the `components` section of the Swagger specification.
134
+
135
+ **Parameters:**
136
+ - `components` (dict): The `components` section of the Swagger specification.
137
+
138
+ **Returns:**
139
+ - `Dict[str, Dict]`: Resolved and preprocessed components organized by type (e.g., schemas, parameters).
140
+
141
+ ---
142
+
143
+ ### 6. `resolve_schema(schema: dict, resolved_components: dict, visited_refs: set) -> dict`
144
+ Recursively resolves `$ref` references in schemas while avoiding circular references.
145
+
146
+ **Parameters:**
147
+ - `schema` (dict): The schema to resolve.
148
+ - `resolved_components` (dict): Preprocessed components for reference resolution.
149
+ - `visited_refs` (set): Tracks references to avoid circular references.
150
+
151
+ **Returns:**
152
+ - `dict`: Fully resolved schema.
153
+
154
+ ---
155
+
156
+ ### 7. `extract_metadata(data: dict) -> Dict[str, Any]`
157
+ Extracts high-level metadata from the root of the Swagger specification, such as `host`, `basePath`, and `servers`.
158
+
159
+ **Parameters:**
160
+ - `data` (dict): The full Swagger/OpenAPI specification.
161
+
162
+ **Returns:**
163
+ - `Dict[str, Any]`: Metadata like `host`, `basePath`, `schemes`, and `servers`.
164
+
165
+ ---
166
+
167
+ ### 8. `generate_request_body_from_schema(schema: dict, resolved_components: dict) -> Optional[Union[dict, list, str, int, bool]]`
168
+ Generates an example request body based on a schema definition.
169
+
170
+ **Parameters:**
171
+ - `schema` (dict): The schema definition.
172
+ - `resolved_components` (dict): Resolved components for reference resolution.
173
+
174
+ **Returns:**
175
+ - `Optional[Union[dict, list, str, int, bool]]`: An example request body.
176
+
177
+ ---
@@ -0,0 +1,12 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ tests/test_complex.py
5
+ tests/test_components.py
6
+ tests/test_library.py
7
+ tests/test_request_body.py
8
+ wapiti_swagger/wapiti_swagger.egg-info/PKG-INFO
9
+ wapiti_swagger/wapiti_swagger.egg-info/SOURCES.txt
10
+ wapiti_swagger/wapiti_swagger.egg-info/dependency_links.txt
11
+ wapiti_swagger/wapiti_swagger.egg-info/requires.txt
12
+ wapiti_swagger/wapiti_swagger.egg-info/top_level.txt