Add docs

Author: luolingchun

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/assets/Snipaste_2025-01-14_10-44-00.png

@@ -53,6 +53,8 @@ class ContentTypeModel(BaseModel):
 @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 ...

docs/assets/Snipaste_2025-01-14_10-49-19.png

@@ -7,9 +7,16 @@
 import sys
 from enum import Enum
 from http import HTTPStatus
-from typing import Any, Callable, DefaultDict, Optional, Type, get_type_hints, Union
-from types import UnionType
-from flask import current_app, make_response
+from typing import Dict, Type, Callable, List, Tuple, Optional, Any, DefaultDict, Union
+from typing import get_args, get_origin, get_type_hints
+
+try:
+    from types import UnionType  # type: ignore
+except ImportError:  # pragma: no cover
+    # python < 3.10
+    UnionType = Union  # type: ignore
+
+from flask import make_response, current_app
 from flask.wrappers import Response as FlaskResponse
 from pydantic import BaseModel, ValidationError
 from pydantic.json_schema import JsonSchemaMode