Support multi content type in request body and responses

.github/workflows/tests.yml

@@ -23,7 +23,7 @@ jobs:
     strategy:
       max-parallel: 4
       matrix:
-        python-version: [ "3.9", "3.10", "3.11", "3.12", "3.13" ]
+        python-version: [ "3.10", "3.11", "3.12", "3.13", "3.14" ]
         flask-version: [ "Flask>=2.0,<3.0", "Flask>=3.0" ]
     env:
       PYTHONPATH: .

README.md

@@ -37,7 +37,7 @@ The key features are:
 
 ## Requirements
 
-Python 3.9+
+Python 3.10+
 
 flask-openapi3 is dependent on the following libraries:
 

docs/Usage/Request.md

@@ -167,6 +167,88 @@ def get_book(query: BookQuery, client_id:str = None):
     ...
 ```
 
+## Multiple content types in the request body
+
+```python
+from typing import Union
+
+from flask import Request
+from pydantic import BaseModel
+
+from flask_openapi3 import OpenAPI
+
+app = OpenAPI(__name__)
+
+
+class DogBody(BaseModel):
+    a: int = None
+    b: str = None
+
+    model_config = {
+        "openapi_extra": {
+            "content_type": "application/vnd.dog+json"
+        }
+    }
+
+
+class CatBody(BaseModel):
+    c: int = None
+    d: str = None
+
+    model_config = {
+        "openapi_extra": {
+            "content_type": "application/vnd.cat+json"
+        }
+    }
+
+
+class BsonModel(BaseModel):
+    e: int = None
+    f: str = None
+
+    model_config = {
+        "openapi_extra": {
+            "content_type": "application/bson"
+        }
+    }
+
+
+class ContentTypeModel(BaseModel):
+    model_config = {
+        "openapi_extra": {
+            "content_type": "text/csv"
+        }
+    }
+
+
+@app.post("/a", responses={200: DogBody | CatBody | ContentTypeModel | BsonModel})
+def index_a(body: DogBody | CatBody | ContentTypeModel | BsonModel):
+    """
+    multiple content types examples.
+
+    This may be confusing, if the content-type is application/json, the type of body will be auto parsed to
+    DogBody or CatBody, otherwise it cannot be parsed to ContentTypeModel or BsonModel.
+    The body is equivalent to the request variable in Flask, and you can use body.data, body.text, etc ...
+    """
+    print(body)
+    if isinstance(body, Request):
+        if body.mimetype == "text/csv":
+            # processing csv data
+            ...
+        elif body.mimetype == "application/bson":
+            # processing bson data
+            ...
+    else:
+        # DogBody or CatBody
+        ...
+    return {"hello": "world"}
+```
+
+The effect in swagger:
+
+![](../assets/Snipaste_2025-01-14_10-44-00.png)
+
+
 ## Request model
 
 First, you need to define a [pydantic](https://github.com/pydantic/pydantic) model:
@@ -191,7 +273,7 @@ class BookQuery(BaseModel):
     author: str = Field(None, description='Author', json_schema_extra={"deprecated": True})
 ```
 
-Magic:
+The effect in swagger:
 
 ![](../assets/Snipaste_2022-09-04_10-10-03.png)
 

docs/Usage/Response.md

@@ -56,6 +56,122 @@ def hello(path: HelloPath):
 
 ![image-20210526104627124](../assets/image-20210526104627124.png)
 
+*Sometimes you may need more description fields about the response, such as description, headers and links.
+
+You can use the following form:
+
+```python
+@app.get(
+     "/test",
+     responses={
+         "201": {
+             "model": BaseResponse,
+             "description": "Custom description",
+             "headers": {
+                 "location": {
+                     "description": "URL of the new resource",
+                     "schema": {"type": "string"}
+                 }
+             },
+             "links": {
+                 "dummy": {
+                     "description": "dummy link"
+                 }
+             }
+         }
+     }
+ )
+ def endpoint_test():
+     ...
+```
+
+The effect in swagger:
+
+![](../assets/Snipaste_2025-01-14_11-08-40.png)
+
+
+## Multiple content types in the responses
+
+```python
+from typing import Union
+
+from flask import Request
+from pydantic import BaseModel
+
+from flask_openapi3 import OpenAPI
+
+app = OpenAPI(__name__)
+
+
+class DogBody(BaseModel):
+    a: int = None
+    b: str = None
+
+    model_config = {
+        "openapi_extra": {
+            "content_type": "application/vnd.dog+json"
+        }
+    }
+
+
+class CatBody(BaseModel):
+    c: int = None
+    d: str = None
+
+    model_config = {
+        "openapi_extra": {
+            "content_type": "application/vnd.cat+json"
+        }
+    }
+
+
+class BsonModel(BaseModel):
+    e: int = None
+    f: str = None
+
+    model_config = {
+        "openapi_extra": {
+            "content_type": "application/bson"
+        }
+    }
+
+
+class ContentTypeModel(BaseModel):
+    model_config = {
+        "openapi_extra": {
+            "content_type": "text/csv"
+        }
+    }
+
+
+@app.post("/a", responses={200: DogBody | CatBody | ContentTypeModel | BsonModel})
+def index_a(body: DogBody | CatBody | ContentTypeModel | BsonModel):
+    """
+    multiple content types examples.
+
+    This may be confusing, if the content-type is application/json, the type of body will be auto parsed to
+    DogBody or CatBody, otherwise it cannot be parsed to ContentTypeModel or BsonModel.
+    The body is equivalent to the request variable in Flask, and you can use body.data, body.text, etc ...
+    """
+    print(body)
+    if isinstance(body, Request):
+        if body.mimetype == "text/csv":
+            # processing csv data
+            ...
+        elif body.mimetype == "application/bson":
+            # processing bson data
+            ...
+    else:
+        # DogBody or CatBody
+        ...
+    return {"hello": "world"}
+```
+
+The effect in swagger:
+
+![](../assets/Snipaste_2025-01-14_10-49-19.png)
+
+
 ## More information about OpenAPI responses
 
 - [OpenAPI Responses Object](https://spec.openapis.org/oas/v3.1.0#responses-object), it includes the Response Object.

docs/Usage/Route_Operation.md

@@ -289,6 +289,29 @@ class BookListAPIView:
 app.register_api_view(api_view)
 ```
 
+## request_body_description
+
+A brief description of the request body.
+
+```python
+from flask_openapi3 import OpenAPI
+
+app = OpenAPI(__name__)
+
+@app.post(
+    "/",
+    request_body_description="A brief description of the request body."
+)
+def create_book(body: Bookbody):
+    ...
+```
+
+![](../assets/Snipaste_2025-01-14_10-56-40.png)
+
+## request_body_required
+
+Determines if the request body is required in the request.
+
 ## doc_ui
 
 You can pass `doc_ui=False` to disable the `OpenAPI spec` when init `OpenAPI `.

docs/index.zh.md

@@ -32,7 +32,7 @@
 
 ## 依赖
 
-Python 3.9+
+Python 3.10+
 
 flask-openapi3 依赖以下库：
 

examples/api_blueprint_demo.py

@@ -2,7 +2,6 @@
 # @Author  : llc
 # @Time    : 2021/6/6 14:05
 
-from typing import Optional
 
 from pydantic import BaseModel, Field
 
@@ -37,7 +36,7 @@ class Unauthorized(BaseModel):
 
 
 class BookBody(BaseModel):
-    age: Optional[int] = Field(..., ge=2, le=4, description="Age")
+    age: int | None = Field(..., ge=2, le=4, description="Age")
     author: str = Field(None, min_length=2, max_length=4, description="Author")
 
 

examples/api_view_demo.py

@@ -1,7 +1,6 @@
 # -*- coding: utf-8 -*-
 # @Author  : llc
 # @Time    : 2022/10/18 9:00
-from typing import Optional
 
 from pydantic import BaseModel, Field
 
@@ -22,11 +21,11 @@ class BookPath(BaseModel):
 
 
 class BookQuery(BaseModel):
-    age: Optional[int] = Field(None, description="Age")
+    age: int | None = Field(None, description="Age")
 
 
 class BookBody(BaseModel):
-    age: Optional[int] = Field(..., ge=2, le=4, description="Age")
+    age: int | None = Field(..., ge=2, le=4, description="Age")
     author: str = Field(None, min_length=2, max_length=4, description="Author")
 
 

examples/async_demo.py

@@ -2,7 +2,6 @@
 # @Author  : llc
 # @Time    : 2022/11/30 14:55
 
-from typing import Optional
 
 from pydantic import BaseModel, Field
 
@@ -17,11 +16,11 @@ class Query(BaseModel):
 
 
 class BookQuery(BaseModel):
-    age: Optional[int] = Field(None, description="Age")
+    age: int | None = Field(None, description="Age")
 
 
 class BookBody(BaseModel):
-    age: Optional[int] = Field(..., ge=2, le=4, description="Age")
+    age: int | None = Field(..., ge=2, le=4, description="Age")
     author: str = Field(None, min_length=2, max_length=4, description="Author")