flask-ast-openapi 0.2.0__tar.gz → 0.2.2__tar.gz

{flask_ast_openapi-0.2.0 → flask_ast_openapi-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flask-ast-openapi
-Version: 0.2.0
+Version: 0.2.2
 Summary: Generate OpenAPI specifications from Flask source code using AST
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -55,6 +55,8 @@ It also provides optional Swagger UI integration for Flask applications.
 * Marshmallow request schema support
 * Marshmallow response schema support
 * Cross-file Marshmallow schema resolution
+* Automatic request content-type detection for JSON and multipart forms
+* Request and response content-type docstring overrides
 * Nested Marshmallow schema support
 * OpenAPI component schema generation
 * Configurable authentication decorators
@@ -431,6 +433,23 @@ def create_user():
     ...
 ```
 
+JSON bodies are detected from `request.get_json()` and `request.json`.
+Multipart bodies are detected from `request.form` and `request.files`.
+For custom media types, use docstring directives:
+
+```python
+@app.post("/documents")
+def upload_document():
+    """
+    :request: DocumentUploadSchema
+    :response: DocumentResponseSchema
+    :request-content-type: multipart/form-data
+    :response-content-type: application/json
+    """
+
+    ...
+```
+
 The generator detects `UserRequestSchema` and creates an OpenAPI request-body schema.
 
 ## Response Schemas
@@ -785,12 +804,12 @@ Future development may include:
 Current version:
 
 ```text
-0.2.0
+0.2.1
 ```
 
-Version `0.2.0` adds nested cross-file Blueprint prefix resolution,
-automatic Blueprint tags, cross-file Marshmallow schema resolution, and
-default exclusion of test and virtual-environment directories.
+Version `0.2.1` adds automatic JSON and multipart request content-type
+detection, explicit request/response media-type overrides, and avoids creating
+request bodies for header-only and path-only inputs.
 
 ## License
 

flask_ast_openapi-0.2.0/src/flask_ast_openapi.egg-info/PKG-INFO → flask_ast_openapi-0.2.2/README.md

@@ -1,15 +1,3 @@
-Metadata-Version: 2.4
-Name: flask-ast-openapi
-Version: 0.2.0
-Summary: Generate OpenAPI specifications from Flask source code using AST
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: Flask>=3.0
-Provides-Extra: dev
-Requires-Dist: pytest>=8; extra == "dev"
-Dynamic: license-file
-
 # flask-ast-openapi
 
 Generate OpenAPI 3 specifications from Flask source code using Python's Abstract Syntax Tree (AST).
@@ -31,10 +19,10 @@ It also provides optional Swagger UI integration for Flask applications.
   * `@app.put(...)`
   * `@app.patch(...)`
   * `@app.delete(...)`
-* Blueprint route support
-* Blueprint `url_prefix` support
-* Nested and cross-file Blueprint registration support
-* Automatic Blueprint tags for Swagger UI grouping
+* Blueprint route support
+* Blueprint `url_prefix` support
+* Nested and cross-file Blueprint registration support
+* Automatic Blueprint tags for Swagger UI grouping
 * Flask path parameter conversion to OpenAPI format
 * Flask converter support:
 
@@ -53,8 +41,10 @@ It also provides optional Swagger UI integration for Flask applications.
 * Function docstrings as OpenAPI descriptions
 * Synchronous and asynchronous Flask route support
 * Marshmallow request schema support
-* Marshmallow response schema support
-* Cross-file Marshmallow schema resolution
+* Marshmallow response schema support
+* Cross-file Marshmallow schema resolution
+* Automatic request content-type detection for JSON and multipart forms
+* Request and response content-type docstring overrides
 * Nested Marshmallow schema support
 * OpenAPI component schema generation
 * Configurable authentication decorators
@@ -417,7 +407,7 @@ class UserRequestSchema(Schema):
     active = fields.Boolean()
 ```
 
-A route can reference the schema from its docstring:
+A route can reference the schema from its docstring:
 
 ```python
 @app.post("/users")
@@ -428,8 +418,25 @@ def create_user():
     :request: UserRequestSchema
     """
 
-    ...
-```
+    ...
+```
+
+JSON bodies are detected from `request.get_json()` and `request.json`.
+Multipart bodies are detected from `request.form` and `request.files`.
+For custom media types, use docstring directives:
+
+```python
+@app.post("/documents")
+def upload_document():
+    """
+    :request: DocumentUploadSchema
+    :response: DocumentResponseSchema
+    :request-content-type: multipart/form-data
+    :response-content-type: application/json
+    """
+
+    ...
+```
 
 The generator detects `UserRequestSchema` and creates an OpenAPI request-body schema.
 
@@ -782,15 +789,15 @@ Future development may include:
 
 ## Version
 
-Current version:
-
-```text
-0.2.0
-```
-
-Version `0.2.0` adds nested cross-file Blueprint prefix resolution,
-automatic Blueprint tags, cross-file Marshmallow schema resolution, and
-default exclusion of test and virtual-environment directories.
+Current version:
+
+```text
+0.2.1
+```
+
+Version `0.2.1` adds automatic JSON and multipart request content-type
+detection, explicit request/response media-type overrides, and avoids creating
+request bodies for header-only and path-only inputs.
 
 ## License
 

{flask_ast_openapi-0.2.0 → flask_ast_openapi-0.2.2}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flask-ast-openapi"
-version = "0.2.0"
+version = "0.2.2"
 description = "Generate OpenAPI specifications from Flask source code using AST"
 readme = "README.md"
 requires-python = ">=3.10"

{flask_ast_openapi-0.2.0 → flask_ast_openapi-0.2.2}/src/flask_ast_openapi/generator.py

@@ -32,8 +32,10 @@ class RouteDefinition:
     auth_schemes: list[str] = field(default_factory=list)
     auth_scheme_mode: str = "and"
     description: str | None = None
-    request_schema: dict[str, Any] | None = None
+    request_schema: dict[str, Any] | None = None
     response_schema: dict[str, Any] | None = None
+    request_content_type: str | None = "application/json"
+    response_content_type: str = "application/json"
     tag: str | None = None
 @dataclass
 class PathParameter:
@@ -283,10 +285,16 @@ class FlaskASTOpenAPI:
                                 function
                             )
                         ),
-                        request_schema=self.build_request_schema_from_docstring(
-                            tree,
-                            function,
-                        ),
+                        request_schema=self.build_request_schema_from_docstring(
+                            tree,
+                            function,
+                        ),
+                        request_content_type=(
+                            self.extract_request_content_type(function)
+                        ),
+                        response_content_type=(
+                            self.extract_response_content_type(function)
+                        ),
                         uses_json_body=(
                             self.function_uses_json_body(
                                 function
@@ -422,11 +430,12 @@ class FlaskASTOpenAPI:
             route.path
         )
 
-        parameters.extend(
-            self.build_query_parameters_from_names(
-                route.query_parameter_names
-            )
-        )
+        parameters.extend(
+            self.build_query_parameters_from_names(
+                route.query_parameter_names,
+                route.request_schema,
+            )
+        )
         response_status_codes = list(
             route.response_status_codes
         )
@@ -451,16 +460,20 @@ class FlaskASTOpenAPI:
         operation: dict[str, Any] = {
             "operationId": route.function_name,
             "parameters": parameters,
-            "responses": self.build_openapi_responses(
-                response_status_codes,
-                response_schemas,
-            ),
+            "responses": self.build_openapi_responses(
+                response_status_codes,
+                response_schemas,
+                route.response_content_type,
+            ),
         }
 
         if route.tag:
             operation["tags"] = [route.tag]
 
-        if route.uses_json_body or route.request_schema is not None:
+        if (
+            route.request_content_type is not None
+            and (route.uses_json_body or route.request_schema is not None)
+        ):
             request_schema = route.request_schema
 
             if request_schema is None:
@@ -471,12 +484,12 @@ class FlaskASTOpenAPI:
                 )
 
             operation["requestBody"] = {
-                "required": True,
-                "content": {
-                    "application/json": {
-                        "schema": request_schema,
-                    }
-                },
+                "required": True,
+                "content": {
+                    route.request_content_type: {
+                        "schema": request_schema,
+                    }
+                },
         }
 
         if route.description:
@@ -781,21 +794,34 @@ class FlaskASTOpenAPI:
             )
 
         return parameters
-    def build_query_parameters_from_names(self,names: list[str],) -> list[dict[str, Any]]:
-        """Build OpenAPI query parameters from their names."""
-
-        return [
-            {
-                "name": name,
-                "in": "query",
-                "required": False,
-                "schema": {
-                    "type": "string",
-                },
-            }
-            for name in names
-        ]
-    def function_uses_json_body(self,function: ast.FunctionDef | ast.AsyncFunctionDef,) -> bool:
+    def build_query_parameters_from_names(
+        self,
+        names: list[str],
+        request_schema: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Build OpenAPI query parameters from their names."""
+
+        schema_properties = (
+            request_schema.get("properties", {})
+            if request_schema
+            else {}
+        )
+        required_names = set(
+            request_schema.get("required", [])
+            if request_schema
+            else []
+        )
+
+        return [
+            {
+                "name": name,
+                "in": "query",
+                "required": name in required_names,
+                "schema": schema_properties.get(name, {"type": "string"}),
+            }
+            for name in names
+        ]
+    def function_uses_json_body(self,function: ast.FunctionDef | ast.AsyncFunctionDef,) -> bool:
         """Check whether a route function reads a JSON request body."""
 
         for node in ast.walk(function):
@@ -816,7 +842,79 @@ class FlaskASTOpenAPI:
                 ):
                     return True
 
-        return False 
+        return False 
+
+    def function_uses_multipart_body(
+        self,
+        function: ast.FunctionDef | ast.AsyncFunctionDef,
+    ) -> bool:
+        """Check whether a route reads form fields or uploaded files."""
+
+        for node in ast.walk(function):
+            if not isinstance(node, ast.Attribute):
+                continue
+
+            if (
+                isinstance(node.value, ast.Name)
+                and node.value.id == "request"
+                and node.attr in {"form", "files"}
+            ):
+                return True
+
+        return False
+
+    def extract_docstring_directive(
+        self,
+        function: ast.FunctionDef | ast.AsyncFunctionDef,
+        directive: str,
+    ) -> str | None:
+        """Extract a named ``:directive: value`` from a docstring."""
+
+        docstring = ast.get_docstring(function)
+        if not docstring:
+            return None
+
+        match = re.search(
+            rf"^\s*:{re.escape(directive)}:\s*([^\s]+)",
+            docstring,
+            re.MULTILINE,
+        )
+        return match.group(1) if match else None
+
+    def extract_request_content_type(
+        self,
+        function: ast.FunctionDef | ast.AsyncFunctionDef,
+    ) -> str | None:
+        """Infer request body media type, allowing a docstring override."""
+
+        explicit = self.extract_docstring_directive(
+            function,
+            "request-content-type",
+        )
+        if explicit:
+            return explicit
+
+        if self.function_uses_multipart_body(function):
+            return "multipart/form-data"
+
+        if self.function_uses_json_body(function):
+            return "application/json"
+
+        return None
+
+    def extract_response_content_type(
+        self,
+        function: ast.FunctionDef | ast.AsyncFunctionDef,
+    ) -> str:
+        """Return the declared response media type or JSON by default."""
+
+        return (
+            self.extract_docstring_directive(
+                function,
+                "response-content-type",
+            )
+            or "application/json"
+        )
     def extract_json_body_field_names(self,function: ast.FunctionDef | ast.AsyncFunctionDef,) -> list[str]:
         """Extract JSON body field names used inside a route function."""
 
@@ -1151,10 +1249,11 @@ class FlaskASTOpenAPI:
                 status_codes.append(status_code)
 
         return status_codes
-    def build_openapi_responses(
-    self,
-    status_codes: list[int],
-    response_schemas: dict[int, dict[str, Any]] | None = None,
+    def build_openapi_responses(
+        self,
+        status_codes: list[int],
+        response_schemas: dict[int, dict[str, Any]] | None = None,
+        content_type: str = "application/json",
 ) -> dict[str, Any]:
         """Build OpenAPI responses from status codes and schemas."""
 
@@ -1176,11 +1275,11 @@ class FlaskASTOpenAPI:
             schema = response_schemas.get(status_code)
 
             if schema:
-                response["content"] = {
-                    "application/json": {
-                        "schema": schema,
-                    }
-                }
+                response["content"] = {
+                    content_type: {
+                        "schema": schema,
+                    }
+                }
 
             responses[str(status_code)] = response
 

flask_ast_openapi-0.2.0/README.md → flask_ast_openapi-0.2.2/src/flask_ast_openapi.egg-info/PKG-INFO

@@ -1,3 +1,15 @@
+Metadata-Version: 2.4
+Name: flask-ast-openapi
+Version: 0.2.2
+Summary: Generate OpenAPI specifications from Flask source code using AST
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Flask>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
 # flask-ast-openapi
 
 Generate OpenAPI 3 specifications from Flask source code using Python's Abstract Syntax Tree (AST).
@@ -19,10 +31,10 @@ It also provides optional Swagger UI integration for Flask applications.
   * `@app.put(...)`
   * `@app.patch(...)`
   * `@app.delete(...)`
-* Blueprint route support
-* Blueprint `url_prefix` support
-* Nested and cross-file Blueprint registration support
-* Automatic Blueprint tags for Swagger UI grouping
+* Blueprint route support
+* Blueprint `url_prefix` support
+* Nested and cross-file Blueprint registration support
+* Automatic Blueprint tags for Swagger UI grouping
 * Flask path parameter conversion to OpenAPI format
 * Flask converter support:
 
@@ -41,8 +53,10 @@ It also provides optional Swagger UI integration for Flask applications.
 * Function docstrings as OpenAPI descriptions
 * Synchronous and asynchronous Flask route support
 * Marshmallow request schema support
-* Marshmallow response schema support
-* Cross-file Marshmallow schema resolution
+* Marshmallow response schema support
+* Cross-file Marshmallow schema resolution
+* Automatic request content-type detection for JSON and multipart forms
+* Request and response content-type docstring overrides
 * Nested Marshmallow schema support
 * OpenAPI component schema generation
 * Configurable authentication decorators
@@ -419,6 +433,23 @@ def create_user():
     ...
 ```
 
+JSON bodies are detected from `request.get_json()` and `request.json`.
+Multipart bodies are detected from `request.form` and `request.files`.
+For custom media types, use docstring directives:
+
+```python
+@app.post("/documents")
+def upload_document():
+    """
+    :request: DocumentUploadSchema
+    :response: DocumentResponseSchema
+    :request-content-type: multipart/form-data
+    :response-content-type: application/json
+    """
+
+    ...
+```
+
 The generator detects `UserRequestSchema` and creates an OpenAPI request-body schema.
 
 ## Response Schemas
@@ -770,15 +801,15 @@ Future development may include:
 
 ## Version
 
-Current version:
-
-```text
-0.2.0
-```
-
-Version `0.2.0` adds nested cross-file Blueprint prefix resolution,
-automatic Blueprint tags, cross-file Marshmallow schema resolution, and
-default exclusion of test and virtual-environment directories.
+Current version:
+
+```text
+0.2.1
+```
+
+Version `0.2.1` adds automatic JSON and multipart request content-type
+detection, explicit request/response media-type overrides, and avoids creating
+request bodies for header-only and path-only inputs.
 
 ## License
 

{flask_ast_openapi-0.2.0 → flask_ast_openapi-0.2.2}/tests/test_generator.py

@@ -908,7 +908,7 @@ def get_users():
     ]
 
 
-def test_build_openapi_operation_includes_query_parameters(tmp_path):
+def test_build_openapi_operation_includes_query_parameters(tmp_path):
     generator = FlaskASTOpenAPI(tmp_path)
 
     route = RouteDefinition(
@@ -920,7 +920,7 @@ def test_build_openapi_operation_includes_query_parameters(tmp_path):
 
     operation = generator.build_openapi_operation(route)
 
-    assert operation["parameters"] == [
+    assert operation["parameters"] == [
         {
             "name": "page",
             "in": "query",
@@ -937,10 +937,47 @@ def test_build_openapi_operation_includes_query_parameters(tmp_path):
                 "type": "string",
             },
         },
-    ]
-
-
-def test_build_openapi_operation_combines_path_and_query_parameters(
+    ]
+
+
+def test_build_openapi_operation_uses_request_schema_for_query_parameters(
+    tmp_path,
+):
+    generator = FlaskASTOpenAPI(tmp_path)
+
+    route = RouteDefinition(
+        function_name="get_users",
+        path="/users",
+        methods=["GET"],
+        query_parameter_names=["page", "page_size"],
+        request_schema={
+            "type": "object",
+            "properties": {
+                "page": {"type": "integer"},
+                "page_size": {"type": "integer"},
+            },
+        },
+    )
+
+    operation = generator.build_openapi_operation(route)
+
+    assert operation["parameters"] == [
+        {
+            "name": "page",
+            "in": "query",
+            "required": False,
+            "schema": {"type": "integer"},
+        },
+        {
+            "name": "page_size",
+            "in": "query",
+            "required": False,
+            "schema": {"type": "integer"},
+        },
+    ]
+
+
+def test_build_openapi_operation_combines_path_and_query_parameters(
     tmp_path,
 ):
     generator = FlaskASTOpenAPI(tmp_path)
@@ -6405,3 +6442,89 @@ def create_user():
     response_schema = operation["responses"]["200"]["content"]["application/json"]["schema"]
     assert request_schema["properties"]["name"] == {"type": "string"}
     assert response_schema["properties"]["id"] == {"type": "integer"}
+
+
+def test_generate_infers_multipart_form_data(tmp_path):
+    (tmp_path / "routes.py").write_text(
+        """
+from flask import Blueprint, request
+from marshmallow import Schema, fields
+
+class UploadSchema(Schema):
+    title = fields.String(required=True)
+    file = fields.Raw(required=True)
+
+upload_bp = Blueprint("upload", __name__)
+
+@upload_bp.route("/upload", methods=["POST"])
+def upload():
+    \"\"\":request: UploadSchema\"\"\"
+    title = request.form.get("title")
+    file = request.files.get("file")
+    return {}, 200
+""",
+        encoding="utf-8",
+    )
+
+    spec = FlaskASTOpenAPI(tmp_path).generate()
+    content = spec["paths"]["/upload"]["post"]["requestBody"]["content"]
+
+    assert "multipart/form-data" in content
+    assert "application/json" not in content
+
+
+def test_generate_does_not_create_body_for_header_only_schema(tmp_path):
+    (tmp_path / "routes.py").write_text(
+        """
+from flask import Blueprint, request
+from marshmallow import Schema, fields
+
+class TokenSchema(Schema):
+    token = fields.String(required=True)
+
+auth_bp = Blueprint("auth", __name__)
+
+@auth_bp.route("/validate", methods=["POST"])
+def validate():
+    \"\"\":request: TokenSchema\"\"\"
+    token = request.headers.get("Authorization")
+    return {}, 200
+""",
+        encoding="utf-8",
+    )
+
+    spec = FlaskASTOpenAPI(tmp_path).generate()
+
+    assert "requestBody" not in spec["paths"]["/validate"]["post"]
+
+
+def test_docstring_can_override_request_and_response_content_types(tmp_path):
+    (tmp_path / "routes.py").write_text(
+        """
+from flask import Blueprint, request
+from marshmallow import Schema, fields
+
+class PayloadSchema(Schema):
+    value = fields.String(required=True)
+
+bp = Blueprint("custom", __name__)
+
+@bp.route("/custom", methods=["POST"])
+def custom():
+    \"\"\"
+    :request: PayloadSchema
+    :response: PayloadSchema
+    :request-content-type: application/x-www-form-urlencoded
+    :response-content-type: application/problem+json
+    \"\"\"
+    value = request.form.get("value")
+    return {"value": value}, 200
+""",
+        encoding="utf-8",
+    )
+
+    spec = FlaskASTOpenAPI(tmp_path).generate()
+    operation = spec["paths"]["/custom"]["post"]
+
+    assert "application/x-www-form-urlencoded" in operation["requestBody"]["content"]
+    assert "application/problem+json" in operation["responses"]["200"]["content"]